Distributed Rate Limiter

A production-style distributed rate limiter library for Spring Boot — built the way large-scale systems like Netflix, Cloudflare, and Stripe do it.

---

What This Project Demonstrates

Concept	Implementation
Distributed Systems	Redis-backed rate limiting across multiple servers
Concurrency Safety	Atomic Lua scripts — zero race conditions
Spring Boot Internals	Custom auto-configuration & starter module
AOP	Custom @RateLimit annotation with AspectJ
Algorithm Design	Token Bucket with burst support
SpEL	Dynamic key resolution via Spring Expression Language
Maven	Multi-module project architecture

---

Features

• Token Bucket algorithm with burst support
• Atomic Redis Lua scripting — no race conditions under high concurrency
• Plug-and-play Spring Boot Starter
• Custom @RateLimit annotation
• Dynamic key resolution using SpEL expressions
• Rate limit by User ID, API Key, IP Address, Endpoint, or any custom expression
• Multi-module Maven architecture
• Supports multiple implementations — Redis, in-memory, or custom

---

Tech Stack

Java 21 Spring Boot 4.x Redis Lua AspectJ SpEL Maven

---

Quick Start

1. Add Dependency

<dependency>
    <groupId>com.deepak.rate_limiter</groupId>
    <artifactId>rate-limiter-spring-boot-starter</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

2. Annotate Your API

@RateLimit(
    key = "#userId",
    requests = 10,
    per = 1,
    unit = TimeUnit.SECONDS

3. Dynamic Keys via SpEL

@RateLimit(
    key = "#user.id + ':' + #request.uri",
    requests = 20,
    per = 1,
    unit = TimeUnit.MINUTES
)

---

Architecture

) @GetMapping("/data") public String getData(@RequestParam String userId) { return "success"; }

Client Request
      │
      ▼
Spring Controller
      │
      ▼
@RateLimit Annotation (AOP)
      │
      ▼
RateLimitAspect
      │
      ▼
RedisTokenBucketRateLimiter
      │
      ▼
Redis Lua Script (Atomic)
      │
      ▼
Redis

---

Project Structure

distributed-rate-limiter
├── rate-limiter-core                 # Interfaces, models, abstractions
├── rate-limiter-redis                # Redis + Lua implementation
├── rate-limiter-spring-boot-starter  # Annotation, AOP, Auto-config
└── rate-limiter-example              # Demo Spring Boot app

---

Author

Deepak Rai — Backend Developer | Distributed Systems Enthusiast