sujaydevx/distributed-rate-limiter-service

Purpose and runtime

A Spring Boot Java service implementing distributed, per-client API rate limiting. It runs as an HTTP service, uses Redis as shared mutable state across instances, and exposes Prometheus-compatible metrics. Application startup is src/main/java/com/sujay/ratelimiter/RateLimiterApplication.java; runtime configuration is in src/main/resources/application.yml.

HTTP interception boundary

The servlet filter is the enforcement point: src/main/java/com/sujay/ratelimiter/filter/RateLimitFilter.java. It executes before controllers, derives a client identifier from X-Client-Id (test override), X-Forwarded-For, or source IP, then either:

• permits the request into controller handling, or

• terminates it with HTTP 429, a Retry-After header, and a structured error response.

Controllers are therefore downstream consumers of an already-enforced request path: src/main/java/com/sujay/ratelimiter/controller/RateLimitController.java and src/main/java/com/sujay/ratelimiter/controller/DemoController.java.

Algorithm selection and contract

src/main/java/com/sujay/ratelimiter/service/RateLimiterSelector.java selects the configured implementation, notably token bucket or fixed window. src/main/java/com/sujay/ratelimiter/service/RateLimiterService.java is the common service boundary between the filter and algorithms. Decision results, remaining quota, and retry timing are carried by src/main/java/com/sujay/ratelimiter/model/RateLimitResult.java and related response/info models.

This separation allows algorithm replacement through configuration without changing the HTTP filter or controllers.

Redis-backed enforcement algorithms

src/main/java/com/sujay/ratelimiter/service/FixedWindowRateLimiter.java uses Redis atomic increment semantics for counters scoped by client and time window. It is simple but permits boundary bursts.

src/main/java/com/sujay/ratelimiter/service/TokenBucketRateLimiter.java supports burst capacity plus continuous refill. Its state transition is delegated to Redis Lua to atomically read, refill, consume, and persist bucket state:

• src/main/resources/scripts/token_bucket.lua

• src/main/resources/scripts/sliding_window.lua

src/main/java/com/sujay/ratelimiter/service/SlidingWindowRateLimiter.java is also present as an algorithm component, though the documented configured choices are token bucket and fixed window.

Failure policy and configuration

Redis connectivity and script/template setup are centralized in src/main/java/com/sujay/ratelimiter/config/RedisConfig.java. Rate limits and algorithm selection are bound through src/main/java/com/sujay/ratelimiter/config/RateLimiterProperties.java.

Algorithms handle Redis exceptions with fail-open behavior: requests proceed when Redis is unavailable, favoring API availability over strict quota enforcement. A circuit-breaker metrics configuration exists at src/main/java/com/sujay/ratelimiter/config/CircuitBreakerMetricsConfig.java, but the README identifies active circuit breaking as future scope.

Observability and local infrastructure

Each allow/deny decision is emitted as Prometheus metric ratelimiter_decisions_total, tagged by algorithm and decision. Local dependencies are orchestrated in infra/docker-compose.yml: Redis, Prometheus (infra/prometheus.yml), and Grafana with a provisioned Prometheus datasource (infra/grafana/datasources/prometheus.yml). Load generation targets the HTTP boundary via infra/k6/load-test.js.