spring-boot-bucket4j

A multi-module Kotlin/Spring Boot sample that applies Bucket4j rate limiting in both Spring WebFlux and Spring MVC. The shared core module provides JWT utilities, pricing plan rules, and common constants.

Modules

• core: Shared bucket/plan logic, JWT provider, and constants.
• webflux: Reactive WebFlux application with a WebFilter rate limiter.
• webmvc: Servlet-based Web MVC application with a HandlerInterceptor rate limiter.

Project Structure

core/
  src/main/kotlin/.../application/PricingPlanService.kt
  src/main/kotlin/.../enumerated/PricingPlan.kt
  src/main/kotlin/.../security/JWTProvider.kt
webflux/
  src/main/kotlin/.../configuration/RateLimitInterceptor.kt
  src/main/kotlin/.../presentation/DummyController.kt
  src/main/resources/application.yaml
webmvc/
  src/main/kotlin/.../configuration/RateLimitInterceptor.kt
  src/main/kotlin/.../presentation/DummyController.kt
  src/main/resources/application.yaml
http/request.http

Rate Limiting Behavior

• Buckets are created per token and cached.
• If the token is missing or invalid, the role is treated as ANONYMOUS.
• Pricing plan mapping:
  • ANONYMOUS -> FREE (20 requests/hour)
  • USER -> BASIC (40 requests/hour)
  • PREMIUM / ADMIN -> PROFESSIONAL (100 requests/hour)
• Response headers:
  • X-Rate-Limit-Remaining
  • X-Rate-Limit-Retry-After-Seconds

Run

./gradlew :webflux:bootRun

./gradlew :webmvc:bootRun

Endpoints

• WebFlux: GET http://localhost:1009/webflux
• Web MVC: GET http://localhost:1013/webmvc

Sample HTTP requests are in http/request.http.

References

• https://bucket4j.com/
• https://github.com/bucket4j/bucket4j

Articles

• https://www.baeldung.com/spring-bucket4j
• https://dzone.com/articles/how-to-provide-rate-limiting-via-bucket4j-in-java