Limitly — Redis-Backed Rate Limiter Spring Boot Starter

Limitly is a production-grade, zero-config, annotation-based rate limiting library built for Spring Boot applications powered by Redis. Built with Java 21, Spring Boot 3, and Lua Scripting to ensure race-condition-free, atomic operations across distributed pod replicas.

⚡ Features

• Annotation-based DX: Drop @RateLimit on any @RestController endpoint.
• Atomic Redis Execution: Zero race conditions under high concurrent traffic using Redis Lua scripts (EVALSHA/EVAL).
• Dual Algorithms Supported:
  • Token Bucket: Smoothed traffic flow, configurable refill rates, low Redis memory footprint.
  • Sliding Window Log: Exact request-count precision using Redis Sorted Sets (ZSET).
• Flexible Key Resolution:
  • USER: Resolves user Principal or X-User-ID header.
  • IP: Resolves real client IP (aware of X-Forwarded-For proxy headers).
  • SPEL: Dynamic SpEL expression support (e.g. #request.remoteAddr, #user.id).
• Resilient Fallback Modes:
  • FAIL_OPEN: (Default) Allows request traffic through when Redis is unreachable.
  • FAIL_CLOSED: Throttles requests securely during Redis outages.
• Production Observability: Built-in Micrometer metrics (ratelimiter.requests.allowed, ratelimiter.requests.denied, ratelimiter.redis.latency, ratelimiter.redis.failures) ready for Prometheus and Grafana dashboards.
• RFC-compliant HTTP Headers: Automatically appends X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After HTTP headers on throttled 429 responses.

🏗️ High-Level Architecture

┌───────────────────────────────────────────────────────────┐
│                     Client Request                        │
└────────────────────────┬──────────────────────────────────┘
                         ▼
              ┌─────────────────────┐
              │ RateLimitInterceptor│  (HandlerInterceptor)
              └──────────┬──────────┘
                         │ resolves key via KeyResolver
                         ▼
              ┌─────────────────────┐
              │  RateLimiterService │
              └──────────┬──────────┘
                         │ executes Lua script atomically