kumaran-nk/adaptive-rate-limiter

Purpose and Runtime

This is a Java 21/Spring Boot distributed rate-limiting service designed to keep enforcing limits during Redis degradation. The application entry point is src/main/java/com/ratelimiter/adaptive_rate_limiter/AdaptiveRateLimiterApplication.java; runtime configuration is in src/main/resources/application.properties.

HTTP Enforcement Boundary

Spring MVC receives requests through controllers, while a global interceptor applies rate-limit decisions before protected handler execution. Primary HTTP-facing components are:

• src/main/java/com/ratelimiter/adaptive_rate_limiter/interceptor/RateLimitInterceptor.java

• src/main/java/com/ratelimiter/adaptive_rate_limiter/controller/RateLimitTestController.java

• src/main/java/com/ratelimiter/adaptive_rate_limiter/config/WebMvcConfig.java

Rejections and Redis-related failures are translated at the API boundary by src/main/java/com/ratelimiter/adaptive_rate_limiter/exception/GlobalExceptionHandler.java and src/main/java/com/ratelimiter/adaptive_rate_limiter/exception/RedisExceptionHandler.java.

Rate-Limit Orchestration

src/main/java/com/ratelimiter/adaptive_rate_limiter/service/RateLimiterService.java is the central decision coordinator. It selects a strategy based on the current health state and returns a RateLimitDecision model to the interceptor. The strategy abstraction and concrete policies are:

• src/main/java/com/ratelimiter/adaptive_rate_limiter/service/strategy/RateLimitStrategy.java

• src/main/java/com/ratelimiter/adaptive_rate_limiter/service/strategy/SlidingWindowStrategy.java

• src/main/java/com/ratelimiter/adaptive_rate_limiter/service/strategy/TokenBucketStrategy.java

Redis-Backed Consistent Path

In HEALTHY mode, sliding-window checks use Redis for distributed consistency. src/main/java/com/ratelimiter/adaptive_rate_limiter/service/RedisRateCheckService.java owns Redis checks, and src/main/java/com/ratelimiter/adaptive_rate_limiter/redis/LuaScriptLoader.java loads the atomic Lua implementation at src/main/resources/lua/sliding_window.lua. Redis connectivity and client setup are bounded by src/main/java/com/ratelimiter/adaptive_rate_limiter/config/RedisConfig.java.

Degradation and Local Fallback

When Redis cannot serve checks reliably, the service shifts from Redis-backed sliding windows to cached or local token-bucket limiting. The local state boundary is src/main/java/com/ratelimiter/adaptive_rate_limiter/cache/LocalRateLimitCache.java, configured through src/main/java/com/ratelimiter/adaptive_rate_limiter/config/CacheConfig.java. This deliberately trades distributed consistency for continued request protection.

Self-Healing State Machine

Health drives algorithm/data-source selection across HEALTHY, WARNING, DEGRADED, and RECOVERY states, represented by src/main/java/com/ratelimiter/adaptive_rate_limiter/model/HealthState.java and src/main/java/com/ratelimiter/adaptive_rate_limiter/model/DegradationMode.java. State transitions are governed by:

• src/main/java/com/ratelimiter/adaptive_rate_limiter/service/state/StateMachine.java

• src/main/java/com/ratelimiter/adaptive_rate_limiter/service/health/RedisHealthProbe.java

• src/main/java/com/ratelimiter/adaptive_rate_limiter/service/health/CircuitBreakerMonitor.java

Resilience4j configuration (src/main/java/com/ratelimiter/adaptive_rate_limiter/config/Resilience4jConfig.java) provides the circuit-breaker boundary around Redis failure behavior; recovery reintroduces Redis gradually.

Observability and Deployment

Micrometer metrics for limits and health state are emitted by src/main/java/com/ratelimiter/adaptive_rate_limiter/metrics/RateLimiterMetrics.java and src/main/java/com/ratelimiter/adaptive_rate_limiter/metrics/HealthStateMetrics.java, intended for Prometheus scraping via monitoring/prometheus.yml. The service is containerized by Dockerfile and deployed alongside Redis on Kubernetes through k8s/deployment.yaml, k8s/redis-deployment.yaml, and k8s/hpa.yaml. src/main/java/com/ratelimiter/adaptive_rate_limiter/service/PodDiscoveryService.java indicates cluster-aware pod discovery as an infrastructure integration.