Bucket4j: The Spring Boot Starter

<dependencyManagement>
    <dependencies>
        <!-- the starter pins Bucket4j 8.17.0; this import moves every Bucket4j jar to 8.21.0 -->
        <dependency>
            <groupId>com.bucket4j</groupId>
            <artifactId>bucket4j_jdk17-bom</artifactId>
            <version>8.21.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>com.giffing.bucket4j.spring.boot.starter</groupId>
        <artifactId>starter-servlet</artifactId>
        <version>0.20.0-RC1</version>
    </dependency>
    <dependency>
        <groupId>com.giffing.bucket4j.spring.boot.starter</groupId>
        <artifactId>starter-aop</artifactId>
        <version>0.20.0-RC1</version>
    </dependency>
    <dependency>
        <groupId>com.giffing.bucket4j.spring.boot.starter</groupId>
        <artifactId>cache-jcache</artifactId>
        <version>0.20.0-RC1</version>
    </dependency>
    <!-- Spring Boot 4 has no spring-boot-starter-aop: AspectJ comes from this starter -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-aspectj</artifactId>
    </dependency>
    <!-- the starter validates its properties: a Bean Validation provider is mandatory -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-cache</artifactId>
    </dependency>
    <dependency>
        <groupId>com.github.ben-manes.caffeine</groupId>
        <artifactId>jcache</artifactId>
        <version>3.2.4</version>
    </dependency>
</dependencies>

<dependency>
    <groupId>com.giffing.bucket4j.spring.boot.starter</groupId>
    <artifactId>bucket4j-spring-boot-starter</artifactId>
    <version>0.14.0</version>
</dependency>
<!-- bucket4j-spring-boot-starter-context and the JCache module come with it; add the same
     spring-boot-starter-aspectj, spring-boot-starter-validation, spring-boot-starter-cache
     and Caffeine's jcache as above -->

spring:
  cache:
    type: jcache
    cache-names: buckets
    jcache:
      provider: com.github.benmanes.caffeine.jcache.spi.CaffeineCachingProvider
bucket4j:
  enabled: true
  cache-to-use: jcache
  filters:
    - cache-name: buckets
      url: /books.*
      rate-limits:
        - cache-key: "getHeader('X-API-Key') ?: 'anonymous'"
          bandwidths:
            - capacity: 20
              time: 1
              unit: minutes

status:       429
x-rate-limit-retry-after-seconds: 2
content-type: application/json;charset=ISO-8859-1
body:         { "message": "Too many requests!" }

bucket4j:
  filters:
    - cache-name: buckets
      url: /first
      strategy: first            # only the first applied rate limit is consumed
      rate-limits:
        - cache-key: "'strategy-first'"
          bandwidths: [ { capacity: 100, time: 1, unit: minutes } ]
        - cache-key: "'strategy-first-tight'"
          bandwidths: [ { capacity: 3, time: 1, unit: minutes } ]
    - cache-name: buckets
      url: /all
      strategy: all              # every applied rate limit is consumed, the first rejection wins
      rate-limits:
        - cache-key: "'strategy-all'"
          bandwidths: [ { capacity: 100, time: 1, unit: minutes } ]
        - cache-key: "'strategy-all-tight'"
          bandwidths: [ { capacity: 3, time: 1, unit: minutes } ]

bucket4j:
  cache-to-use: jcache
  filters:
    # skip-condition: requests carrying X-Internal: true are never limited
    - cache-name: buckets
      url: /ping
      rate-limits:
        - cache-key: "'cond-skip'"
          skip-condition: "getHeader('X-Internal') == 'true'"
          bandwidths: [ { capacity: 2, time: 1, unit: minutes } ]
    # execute-predicates: METHOD=POST limits only POST requests to /ping2 (GET passes through)
    - cache-name: buckets
      url: /ping2
      rate-limits:
        - cache-key: "'cond-post'"
          execute-predicates: [ "METHOD=POST" ]
          bandwidths: [ { capacity: 2, time: 1, unit: minutes } ]
    # post-execute-condition: only failed attempts (HTTP 401) consume a token
    - cache-name: buckets
      url: /login-attempt
      rate-limits:
        - cache-key: "'cond-login'"
          post-execute-condition: "getStatus() eq 401"
          bandwidths: [ { capacity: 3, time: 1, unit: minutes } ]

package scratch;

import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Component;

/** Referenced from SpEL as @principals: the authenticated user name, or null when nobody is authenticated (yet). */
@Component("principals")
class Principals {
    public String username() {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        if (authentication == null || !authentication.isAuthenticated() || "anonymousUser".equals(authentication.getName())) {
            return null;
        }
        return authentication.getName();
    }
}

package scratch;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.provisioning.InMemoryUserDetailsManager;
import org.springframework.security.web.SecurityFilterChain;

@Configuration(proxyBeanMethods = false)
class SecurityConfig {

    @Bean
    @Profile("!secured")
    SecurityFilterChain open(HttpSecurity http) throws Exception {
        return http.authorizeHttpRequests(a -> a.anyRequest().permitAll()).csrf(c -> c.disable()).build();
    }

    /** HTTP Basic: the principal only exists after Spring Security's filter chain has run. */
    @Bean
    @Profile("secured")
    SecurityFilterChain basic(HttpSecurity http) throws Exception {
        return http.authorizeHttpRequests(a -> a.requestMatchers("/actuator/**").permitAll().anyRequest().authenticated())
                .httpBasic(b -> { })
                .csrf(c -> c.disable()).build();
    }

    @Bean
    @Profile("secured")
    UserDetailsService users() {
        return new InMemoryUserDetailsManager(
                User.withUsername("ana").password("{noop}demo-only").roles("USER").build(),
                User.withUsername("ben").password("{noop}demo-only").roles("USER").build());
    }
}

# default filter-order (HIGHEST_PRECEDENCE + 10): runs before Spring Security, the principal is not known yet
bucket4j:
  cache-to-use: jcache
  filters:
    - cache-name: buckets
      url: /me
      rate-limits:
        - cache-key: "@principals.username() ?: 'order-default-' + getRemoteAddr()"
          bandwidths: [ { capacity: 2, time: 1, unit: minutes } ]

# filter-order 0 (> -100): runs after Spring Security's filter chain, the principal is known
bucket4j:
  cache-to-use: jcache
  filters:
    - cache-name: buckets
      url: /me
      filter-order: 0
      rate-limits:
        - cache-key: "@principals.username() ?: 'order-after-' + getRemoteAddr()"
          bandwidths: [ { capacity: 2, time: 1, unit: minutes } ]

bucket4j:
  filters:
    - cache-name: buckets
      url: /r1
      http-status-code: SERVICE_UNAVAILABLE
      http-content-type: text/plain;charset=UTF-8
      http-response-body: slow down
      http-response-headers:
        X-Policy: bookshelf-v1
      rate-limits:
        - cache-key: "'r1'"
          bandwidths: [ { capacity: 1, time: 1, unit: minutes } ]
    - cache-name: buckets
      url: /r2
      hide-http-response-headers: true
      http-response-headers:
        X-Policy: bookshelf-v1
      rate-limits:
        - cache-key: "'r2'"
          bandwidths: [ { capacity: 1, time: 1, unit: minutes } ]

package scratch;

import com.giffing.bucket4j.spring.boot.starter.context.IgnoreRateLimiting;
import com.giffing.bucket4j.spring.boot.starter.context.RateLimiting;
import org.springframework.context.annotation.Profile;
import org.springframework.stereotype.Service;

/** Class-level @RateLimiting protects every public method; @IgnoreRateLimiting opts one out. */
@Service
@Profile("annotations")
@RateLimiting(name = "isbn-class", cacheKey = "'isbn-class'")
public class IsbnService {
    /** limited by the class-level annotation */
    public String lookup(String isbn) {
        return "metadata for " + isbn;
    }

    /** never limited */
    @IgnoreRateLimiting
    public String health() {
        return "up";
    }

    /** own configuration, key per ISBN, execute only for non-blank ISBNs, skipped for the test ISBN, fallback when limited */
    @RateLimiting(name = "isbn-per-isbn", cacheKey = "#isbn", executeCondition = "#isbn != ''", skipCondition = "#isbn == '0000000000'",
            fallbackMethodName = "cachedLookup")
    public String lookupLimited(String isbn) {
        return "live " + isbn;
    }

    public String cachedLookup(String isbn) {
        return "cached " + isbn;
    }

    /** ratePerMethod = true adds the method name to the key, so two methods using the same configuration do not share a bucket */
    @RateLimiting(name = "isbn-shared-config", cacheKey = "'k'", ratePerMethod = true)
    public String methodA() { return "a"; }

    @RateLimiting(name = "isbn-shared-config", cacheKey = "'k'", ratePerMethod = true)
    public String methodB() { return "b"; }

    @RateLimiting(name = "isbn-shared-config", cacheKey = "'k2'")
    public String methodC() { return "c"; }

    @RateLimiting(name = "isbn-shared-config", cacheKey = "'k2'")
    public String methodD() { return "d"; }

    /** two overloads with the same method name: the key is prefixed with the method NAME, so they share a bucket */
    @RateLimiting(name = "isbn-shared-config", cacheKey = "'ov'")
    public String overloaded(String s) { return "s"; }

    @RateLimiting(name = "isbn-shared-config", cacheKey = "'ov'")
    public String overloaded(int i) { return "i"; }
}

bucket4j:
  cache-to-use: jcache
  methods:
    - name: isbn-class
      cache-name: buckets
      rate-limit:
        bandwidths: [ { capacity: 2, time: 1, unit: minutes } ]
    - name: isbn-per-isbn
      cache-name: buckets
      rate-limit:
        bandwidths: [ { capacity: 1, time: 1, unit: minutes } ]
    - name: isbn-shared-config
      cache-name: buckets
      rate-limit:
        bandwidths: [ { capacity: 1, time: 1, unit: minutes } ]

package scratch;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import redis.clients.jedis.JedisPool;

/** Boot creates neither a JedisPool nor a Lettuce RedisClient bean: the starter's Redis modules need one. */
@Configuration(proxyBeanMethods = false)
class RedisConfig {

    @Bean(destroyMethod = "close")
    @Profile("redis-jedis")
    JedisPool jedisPool(@Value("${bookshelf.redis.host}") String host, @Value("${bookshelf.redis.port}") int port) {
        return new JedisPool(host, port);
    }

    @Bean(destroyMethod = "shutdown")
    @Profile("redis-lettuce-servlet")
    io.lettuce.core.RedisClient redisClient(@Value("${bookshelf.redis.host}") String host, @Value("${bookshelf.redis.port}") int port) {
        return io.lettuce.core.RedisClient.create(io.lettuce.core.RedisURI.create(host, port));
    }
}

package reactiveapp;

import io.lettuce.core.RedisClient;
import io.lettuce.core.RedisURI;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/** WebFlux Bookshelf with the starter's webflux filter and Redis through Lettuce (needs the RedisClient bean). */
@SpringBootApplication
@RestController
public class ReactiveApplication {

    @GetMapping("/books")
    String books() {
        return "books";
    }

    @Bean(destroyMethod = "shutdown")
    @org.springframework.boot.autoconfigure.condition.ConditionalOnProperty(name = "bookshelf.redis.client", havingValue = "true", matchIfMissing = true)
    RedisClient redisClient(@Value("${bookshelf.redis.host}") String host, @Value("${bookshelf.redis.port}") int port) {
        return RedisClient.create(RedisURI.create(host, port));
    }
}

bucket4j:
  enabled: true
  cache-to-use: redis-lettuce
  filters:
    - cache-name: buckets
      filter-method: webflux
      url: /books.*
      rate-limits:
        - cache-key: "getHeaders().getFirst('X-API-Key') ?: 'reactive-anonymous'"
          bandwidths: [ { capacity: 3, time: 1, unit: minutes } ]
management:
  endpoints:
    web:
      exposure:
        include: health,metrics,bucket4j

bucket4j:
  cache-to-use: jcache
  filter-config-caching-enabled: true
  filter-config-cache-name: filterConfigCache
  filters:
    - id: dynamic-ping
      major-version: 1
      minor-version: 1
      cache-name: buckets
      url: /ping
      rate-limits:
        - cache-key: "'dynamic'"
          tokens-inheritance-strategy: PROPORTIONALLY
          bandwidths: [ { id: per-minute, capacity: 2, time: 1, unit: minutes } ]

Bucket4JConfiguration current = filterConfigs.getValue("dynamic-ping");
Bucket4JConfiguration update = filterConfigs.getValue("dynamic-ping");
update.getRateLimits().get(0).getBandwidths().get(0).setCapacity(10);
update.setMinorVersion(2);
// null when acceptable: a higher version, and no change of filterMethod, filterOrder or cacheName
ResponseEntity<String> problem = Bucket4JUtils.validateConfigurationUpdate(current, update);
if (problem == null) {
    filterConfigs.setValue("dynamic-ping", update);   // CacheManager<String, Bucket4JConfiguration> bean
}

GET /actuator/metrics/bucket4j_summary_consumed
  availableTags: name=[buckets], plan=[anonymous]
  measurements: COUNT 10.0
GET /actuator/metrics/bucket4j_summary_rejected
  measurements: COUNT 2.0
GET /actuator/prometheus
  bucket4j_summary_consumed_total{name="buckets",plan="anonymous"} 10.0
  bucket4j_summary_rejected_total{name="buckets",plan="anonymous"} 2.0

{"servlet":[{"cacheName":"buckets","filterMethod":"SERVLET","filterOrder":-2147483638,"hideHttpResponseHeaders":false,
  "httpContentType":"application/json","httpResponseBody":"{ \"title\": \"Too many requests\", \"status\": 429 }",
  "httpStatusCode":"429 TOO_MANY_REQUESTS","id":"bookshelf-api","majorVersion":1,"minorVersion":1,
  "metrics":{"enabled":true,"tags":[{"expression":"@apiKeys.plan(getHeader('X-API-Key')) ?: 'anonymous'","key":"plan", ...}],
  "types":["CONSUMED_COUNTER","REJECTED_COUNTER","PARKED_COUNTER","INTERRUPTED_COUNTER","DELAYED_COUNTER"]},
  "rateLimits":[{"bandwidths":[{"capacity":200,"refillSpeed":"GREEDY","time":1,"unit":"Minutes", ...}], ...

package scratch;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

import java.util.HashMap;
import java.util.Map;

/** Maps an API key to its plan; referenced from SpEL as @apiKeys. */
@Component("apiKeys")
@ConfigurationProperties(prefix = "bookshelf")
class ApiKeyDirectory {
    private Map<String, String> apiKeys = new HashMap<>();

    public Map<String, String> getApiKeys() { return apiKeys; }
    public void setApiKeys(Map<String, String> apiKeys) { this.apiKeys = apiKeys; }

    /** FREE, PRO, or null for a missing or unknown key. */
    public String plan(String apiKey) {
        return apiKey == null ? null : apiKeys.get(apiKey);
    }
}

# Bookshelf with bucket4j-spring-boot-starter 0.20.0-RC1 (servlet filter + JCache; Caffeine's JCache provider in this scratch app)
bookshelf:
  api-keys:                       # application code: the starter does not know about plans
    free-key-1: FREE
    pro-key-1: PRO

bucket4j:
  enabled: true
  cache-to-use: jcache
  default-http-content-type: application/json
  default-http-response-body: '{ "title": "Too many requests", "status": 429 }'
  default-metric-tags:
    - key: plan
      expression: "@apiKeys.plan(getHeader('X-API-Key')) ?: 'anonymous'"
  filters:
    - id: bookshelf-api
      cache-name: buckets
      url: /books.*
      strategy: first                      # the first rate limit whose conditions match is enforced
      rate-limits:
        # PRO: 200 requests per minute per API key; /books/search costs 5 tokens of the same bucket
        - execute-condition: "@apiKeys.plan(getHeader('X-API-Key')) == 'PRO'"
          execute-predicates: [ "PATH=/books/search" ]
          cache-key: "getHeader('X-API-Key')"
          num-tokens: 5
          bandwidths: [ { capacity: 200, time: 1, unit: minutes } ]
        - execute-condition: "@apiKeys.plan(getHeader('X-API-Key')) == 'PRO'"
          skip-predicates: [ "PATH=/books/search" ]
          cache-key: "getHeader('X-API-Key')"
          bandwidths: [ { capacity: 200, time: 1, unit: minutes } ]
        # FREE: 20 requests per minute per API key; /books/search costs 5 tokens
        - execute-condition: "@apiKeys.plan(getHeader('X-API-Key')) == 'FREE'"
          execute-predicates: [ "PATH=/books/search" ]
          cache-key: "getHeader('X-API-Key')"
          num-tokens: 5
          bandwidths: [ { capacity: 20, time: 1, unit: minutes } ]
        - execute-condition: "@apiKeys.plan(getHeader('X-API-Key')) == 'FREE'"
          skip-predicates: [ "PATH=/books/search" ]
          cache-key: "getHeader('X-API-Key')"
          bandwidths: [ { capacity: 20, time: 1, unit: minutes } ]
        # anonymous (no key, or a key nobody issued): 10 requests per minute per client IP
        - execute-condition: "@apiKeys.plan(getHeader('X-API-Key')) == null"
          execute-predicates: [ "PATH=/books/search" ]
          cache-key: "getRemoteAddr()"
          num-tokens: 5
          bandwidths: [ { capacity: 10, time: 1, unit: minutes } ]
        - execute-condition: "@apiKeys.plan(getHeader('X-API-Key')) == null"
          skip-predicates: [ "PATH=/books/search" ]
          cache-key: "getRemoteAddr()"
          bandwidths: [ { capacity: 10, time: 1, unit: minutes } ]
  methods:
    # the ISBN provider allows 100 lookups per day for the whole account (shared across plans)
    - name: bookshelf-isbn
      cache-name: buckets
      rate-limit:
        bandwidths: [ { capacity: 100, time: 1, unit: days, refill-speed: interval } ]