README.md

Spring Boot Throttling

Overview

Declarative approach of throttling control over the Spring services. @Throttling annotation helps you to limit the number of service method calls per java.util.concurrent.TimeUnit for a particular user, IP address, HTTP header/cookie value, or using Spring Expression Language (SpEL).

Please see example project. Pull requests are welcome.

Getting Started

Gradle setup

Add maven repo to you project

repositories {
 maven { url "https://raw.github.com/weddini/spring-boot-throttling/mvn-repo/" }
}

Add the following code to dependencies section of your build.gradle:

compile('com.weddini.throttling:spring-boot-throttling-starter:0.0.9')

Maven setup

Add this GitHub repository to you project

<repositories>
    <repository>
        <id>spring-boot-throttling-repo</id>
        <url>https://raw.github.com/weddini/spring-boot-throttling/mvn-repo/</url>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
        </snapshots>
    </repository>
</repositories>

Add the following code to dependencies section of your pom.xml:

<dependency>
    <groupId>com.weddini.throttling</groupId>
    <artifactId>spring-boot-throttling-starter</artifactId>
    <version>0.0.9</version>
</dependency>

Samples

Defaults (Remote IP)

The following throttling configuration allows 1 method calls per SECOND for each unique HttpServletRequest#getRemoteAddr(). This is 'defaults' for @Throttling annotation.

@Throttling
public void serviceMethod() {
}

is the same as:

@Throttling(type = ThrottlingType.RemoteAddr, limit = 1, timeUnit = TimeUnit.SECONDS)
public void serviceMethod() {
}

Spring Expression Language (SpEL)

The following throttling configuration allows 3 method calls per MINUTE for each unique userName in model object passed as parameter, i.e. model.getUserName().

Please refer to official docs on SpEL.

@Throttling(type = ThrottlingType.SpEL, expression = "#model.userName", limit = 3, timeUnit = TimeUnit.MINUTES)
public void serviceMethod(Model model) {
    log.info("executing service logic for userName = {}", model.getUserName());
}

Http cookie value

The following throttling configuration allows 24 method calls per DAY for each unique cookie value retrieved from HttpServletRequest#getCookies().

@Throttling(type = ThrottlingType.CookieValue, cookieName = "JSESSIONID", limit = 24, timeUnit = TimeUnit.DAYS)
public void serviceMethod() {
}

Http header value

The following throttling configuration allows 10 method calls per HOUR for each unique header value retrieved from HttpServletRequest#getHeader('X-Forwarded-For').

@Throttling(type = ThrottlingType.HeaderValue, headerName = "X-Forwarded-For", limit = 10, timeUnit = TimeUnit.HOURS)
public void serviceMethod() {
}

User Principal Name

The following throttling configuration allows 1 method calls per HOUR for each unique HttpServletRequest#getUserPrincipal().getName().

@Throttling(type = ThrottlingType.PrincipalName, limit = 1, timeUnit = TimeUnit.HOURS)
public void serviceMethod() {
}

Error handling

ThrottlingException is thrown when method reaches @Throttling configuration limit. Service method won't be executed.

@ResponseStatus(code = HttpStatus.TOO_MANY_REQUESTS, reason = "Too many requests")
public class ThrottlingException extends RuntimeException {
}

License

Spring Boot Throttling is Open Source software released under the Apache 2.0 license.