Add rate-limiter module: fixed window, sliding log/counter, token bucket (locked and lock-free), Redis Lua limiter, Spring Boot 429 interceptor

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017ic4b4DPa89t5pSXDQHE6j
This commit is contained in:
asmhatre
2026-11-17 00:51:23 +05:30
co-authored by Claude Sonnet 5.5
parent 35ef0872de
commit deb924febd
26 changed files with 1027 additions and 0 deletions
+1
View File
@@ -23,6 +23,7 @@ One module per article. This repository currently holds:
| [`stack-queue`](stack-queue/) | Stack and Queue Problems in Java: Balanced Parentheses, Next Greater Element, Min Stack | this commit |
| [`library-management`](library-management/) | Library Management System in Java: Console Version to Spring Boot REST API | this commit |
| [`matrix`](matrix/) | Matrix Programs in Java: Addition, Multiplication, Transpose, Spiral and Rotation | this commit |
| [`rate-limiter`](rate-limiter/) | Low-Level Design: Rate Limiter in Java (Token Bucket, Sliding Window) + Spring Boot | this commit |
## `collections` module
+1
View File
@@ -0,0 +1 @@
target/
+39
View File
@@ -0,0 +1,39 @@
# rate-limiter
Runnable companion for the ankurm.com article
[Low-Level Design: Rate Limiter in Java (Token Bucket, Sliding Window) + Spring Boot](https://ankurm.com/low-level-design-rate-limiter-java-token-bucket-sliding-window/).
Four algorithms behind one interface, a lock-free token bucket, a Redis Lua token bucket (plus the
naive version that over-admits), and a Spring Boot interceptor that answers `429` with `Retry-After`.
| Component | Version | Verified against |
|---|---|---|
| JDK | 25.0.5+8 (Temurin, LTS) | `java -version` |
| Spring Boot | 4.1.2 | `maven-metadata.xml` on Maven Central (latest non-milestone) |
| Jedis | 8.0.2 | `maven-metadata.xml` (latest non-beta); `JedisPooled` is gone, `RedisClient` replaces it |
| JUnit | 6.1.3 | `maven-metadata.xml` |
| Redis | 7.0.15 | `redis-server --version` (tests start their own on port 6392) |
```bash
export JAVA_HOME=/path/to/jdk-25 && export PATH="$JAVA_HOME/bin:$PATH"
cd rate-limiter
mvn test # 17 tests; Redis tests are skipped if redis-server is not installed
./scripts/run-demo.sh # boundary-burst comparison of the four algorithms
./scripts/run-redis-demo.sh # naive GET+INCR vs Lua script, 200 threads, limit 10
```
| Source | What it is |
|---|---|
| `RateLimiter`, `Decision` | the interface and its answer (allowed, or how long to wait) |
| `FixedWindowRateLimiter` | two numbers of state; allows 2x the limit across a window boundary |
| `SlidingWindowLogRateLimiter` | exact; O(limit) memory per key |
| `SlidingWindowCounterRateLimiter` | weighted previous + current window; O(1) memory, approximate |
| `TokenBucketRateLimiter`, `LockFreeTokenBucketRateLimiter` | burst then steady rate; `synchronized` vs `compareAndSet` |
| `KeyedRateLimiter` | one limiter per key via `computeIfAbsent` |
| `ManualClock` | move time by hand so tests never sleep |
| `redis/RedisTokenBucketRateLimiter`, `token_bucket.lua` | the whole bucket update in one atomic script |
| `redis/NaiveRedisRateLimiter`, `redis/RedisRaceDemo` | the wrong answer and the demo that shows it |
| `web/RateLimitedApp`, `web/RateLimitInterceptor` | Spring Boot wiring for `/api/**` |
The race demo's naive count varies per run and per machine: indicative, not asserted. Everything else is
deterministic and asserted by the tests.
+83
View File
@@ -0,0 +1,83 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.ankurm.interviewlab</groupId>
<artifactId>rate-limiter</artifactId>
<version>1.0.0</version>
<packaging>jar</packaging>
<name>java-interview-lab :: rate-limiter</name>
<description>
Runnable companion code for ankurm.com's "Rate Limiter in Java" article: fixed window, sliding window
log, sliding window counter, token bucket (locked and lock-free), a Redis Lua token bucket, and a
Spring Boot interceptor that answers 429.
</description>
<properties>
<maven.compiler.release>25</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<junit.version>6.1.3</junit.version>
<spring-boot.version>4.1.2</spring-boot.version>
<jedis.version>8.0.2</jedis.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.junit</groupId>
<artifactId>junit-bom</artifactId>
<version>${junit.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>${spring-boot.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
<dependency>
<groupId>redis.clients</groupId>
<artifactId>jedis</artifactId>
<version>${jedis.version}</version>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.platform</groupId>
<artifactId>junit-platform-launcher</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.14.0</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.6.0</version>
<configuration>
<argLine>-Xmx512m -Duser.timezone=UTC -Dfile.encoding=UTF-8</argLine>
</configuration>
</plugin>
</plugins>
</build>
</project>
+6
View File
@@ -0,0 +1,6 @@
#!/usr/bin/env bash
# Prints the boundary-burst comparison. Needs JDK 25 and Maven.
set -euo pipefail
cd "$(dirname "$0")/.."
mvn -B -q compile
java -cp target/classes com.ankurm.interviewlab.ratelimiter.BoundaryBurstDemo 2>&1 | grep -v '^Picked up JAVA_TOOL_OPTIONS'
+10
View File
@@ -0,0 +1,10 @@
#!/usr/bin/env bash
# Starts a throwaway redis-server on 6391, runs the race demo, stops it. Needs JDK 25, Maven, redis-server.
set -euo pipefail
cd "$(dirname "$0")/.."
mvn -B -q compile dependency:build-classpath -Dmdep.outputFile=target/cp.txt >/dev/null
redis-server --port 6391 --save "" --appendonly no >/dev/null 2>&1 &
REDIS_PID=$!
trap 'kill $REDIS_PID' EXIT
sleep 1
java -cp "target/classes:$(cat target/cp.txt)" com.ankurm.interviewlab.ratelimiter.redis.RedisRaceDemo 6391 2>&1 | grep -v '^Picked up JAVA_TOOL_OPTIONS'
@@ -0,0 +1,43 @@
package com.ankurm.interviewlab.ratelimiter;
import java.time.Duration;
import java.util.function.LongSupplier;
/**
* Limit: 5 requests per 10 seconds. A client sends 5 requests at t=9s and 5 more at t=11s -
* 10 requests in 2 seconds. Which limiters notice?
* Run it with scripts/run-demo.sh.
*/
public final class BoundaryBurstDemo {
public static void main(String[] args) {
long window = Duration.ofSeconds(10).toNanos();
System.out.println("Limit 5 per 10s. Client sends 5 requests at t=9s, then 5 at t=11s.");
System.out.println();
System.out.printf("%-26s %-10s %-10s %s%n", "algorithm", "t=9s", "t=11s", "total in 2s");
run("fixed window", c -> new FixedWindowRateLimiter(5, window, c));
run("sliding window log", c -> new SlidingWindowLogRateLimiter(5, window, c));
run("sliding window counter", c -> new SlidingWindowCounterRateLimiter(5, window, c));
run("token bucket (5, 0.5/s)", c -> new TokenBucketRateLimiter(5, 0.5, c));
}
private static void run(String name, java.util.function.Function<LongSupplier, RateLimiter> factory) {
ManualClock clock = new ManualClock();
RateLimiter limiter = factory.apply(clock);
clock.set(Duration.ofSeconds(9));
int first = burst(limiter, 5);
clock.set(Duration.ofSeconds(11));
int second = burst(limiter, 5);
System.out.printf("%-26s %-10s %-10s %d%n", name, first + "/5", second + "/5", first + second);
}
private static int burst(RateLimiter limiter, int n) {
int ok = 0;
for (int i = 0; i < n; i++) {
if (limiter.tryAcquire().allowed()) {
ok++;
}
}
return ok;
}
}
@@ -0,0 +1,25 @@
package com.ankurm.interviewlab.ratelimiter;
import java.util.concurrent.TimeUnit;
/**
* The answer a limiter gives: let the request through, or reject it and say how long to wait.
* Returning the wait lets an HTTP layer fill in {@code Retry-After} instead of guessing.
*/
public record Decision(boolean allowed, long retryAfterNanos) {
private static final Decision ALLOWED = new Decision(true, 0);
public static Decision permitted() {
return ALLOWED;
}
public static Decision denied(long retryAfterNanos) {
return new Decision(false, Math.max(1, retryAfterNanos));
}
/** Whole seconds, rounded up, never less than 1 - the unit the Retry-After header uses. */
public long retryAfterSeconds() {
return Math.max(1, TimeUnit.NANOSECONDS.toSeconds(retryAfterNanos + 999_999_999L));
}
}
@@ -0,0 +1,39 @@
package com.ankurm.interviewlab.ratelimiter;
import java.util.function.LongSupplier;
/**
* Fixed window counter: time is cut into aligned windows (0-10s, 10-20s, ...) and each window gets
* {@code limit} requests. Smallest possible state (two numbers), but a client can spend {@code limit}
* at the end of one window and {@code limit} more at the start of the next: 2x the limit in a blink.
*/
public final class FixedWindowRateLimiter implements RateLimiter {
private final int limit;
private final long windowNanos;
private final LongSupplier clock;
private long windowStart = Long.MIN_VALUE;
private int count;
public FixedWindowRateLimiter(int limit, long windowNanos, LongSupplier clock) {
this.limit = limit;
this.windowNanos = windowNanos;
this.clock = clock;
}
@Override
public synchronized Decision tryAcquire() {
long now = clock.getAsLong();
long currentWindow = Math.floorDiv(now, windowNanos) * windowNanos;
if (currentWindow != windowStart) {
windowStart = currentWindow;
count = 0;
}
if (count < limit) {
count++;
return Decision.permitted();
}
return Decision.denied(windowStart + windowNanos - now);
}
}
@@ -0,0 +1,27 @@
package com.ankurm.interviewlab.ratelimiter;
import java.util.concurrent.ConcurrentHashMap;
import java.util.function.Supplier;
/**
* One limiter per key (user id, API key, IP). computeIfAbsent guarantees two threads racing on a new
* key end up sharing one limiter instead of each creating their own and doubling the quota.
* Note: entries are never evicted here - production code needs expiry (see the article's callout).
*/
public final class KeyedRateLimiter {
private final ConcurrentHashMap<String, RateLimiter> limiters = new ConcurrentHashMap<>();
private final Supplier<RateLimiter> factory;
public KeyedRateLimiter(Supplier<RateLimiter> factory) {
this.factory = factory;
}
public Decision tryAcquire(String key) {
return limiters.computeIfAbsent(key, k -> factory.get()).tryAcquire();
}
public int trackedKeys() {
return limiters.size();
}
}
@@ -0,0 +1,44 @@
package com.ankurm.interviewlab.ratelimiter;
import java.util.concurrent.atomic.AtomicReference;
import java.util.function.LongSupplier;
/**
* The same token bucket without a lock. The whole state (tokens, last refill time) is one immutable
* record; a request computes the next state and publishes it with compareAndSet, retrying if another
* thread got there first. Two numbers must change together, so they live in one object - two separate
* atomics could be observed half-updated.
*/
public final class LockFreeTokenBucketRateLimiter implements RateLimiter {
private record State(double tokens, long lastRefill) {}
private final double capacity;
private final double refillPerNano;
private final LongSupplier clock;
private final AtomicReference<State> state;
public LockFreeTokenBucketRateLimiter(int capacity, double refillPerSecond, LongSupplier clock) {
this.capacity = capacity;
this.refillPerNano = refillPerSecond / 1_000_000_000.0;
this.clock = clock;
this.state = new AtomicReference<>(new State(capacity, clock.getAsLong()));
}
@Override
public Decision tryAcquire() {
while (true) {
State current = state.get();
long now = clock.getAsLong();
double refilled = Math.min(capacity, current.tokens() + Math.max(0, now - current.lastRefill()) * refillPerNano);
if (refilled < 1.0) {
// Deny without writing: nothing to spend, and a stale read only makes us wait slightly longer.
return Decision.denied((long) Math.ceil((1.0 - refilled) / refillPerNano));
}
State next = new State(refilled - 1.0, Math.max(now, current.lastRefill()));
if (state.compareAndSet(current, next)) {
return Decision.permitted();
}
}
}
}
@@ -0,0 +1,27 @@
package com.ankurm.interviewlab.ratelimiter;
import java.time.Duration;
import java.util.concurrent.atomic.AtomicLong;
import java.util.function.LongSupplier;
/**
* A clock you move by hand, so a test or demo can say "10 seconds later" without sleeping.
* Every limiter takes a {@link LongSupplier} of nanoseconds; production passes {@code System::nanoTime}.
*/
public final class ManualClock implements LongSupplier {
private final AtomicLong nanos = new AtomicLong();
@Override
public long getAsLong() {
return nanos.get();
}
public void advance(Duration d) {
nanos.addAndGet(d.toNanos());
}
public void set(Duration sinceStart) {
nanos.set(sinceStart.toNanos());
}
}
@@ -0,0 +1,8 @@
package com.ankurm.interviewlab.ratelimiter;
/** One limiter guards one key (one user, one API key, one IP). Implementations must be thread-safe. */
public interface RateLimiter {
/** Try to spend one request. Never blocks. */
Decision tryAcquire();
}
@@ -0,0 +1,44 @@
package com.ankurm.interviewlab.ratelimiter;
import java.util.function.LongSupplier;
/**
* Sliding window counter: keep only the previous and current fixed-window counts and weigh the
* previous one by how much of it still overlaps the sliding window. An approximation (it assumes the
* previous window's requests were evenly spread) but O(1) memory and no 2x boundary burst.
*/
public final class SlidingWindowCounterRateLimiter implements RateLimiter {
private final int limit;
private final long windowNanos;
private final LongSupplier clock;
private long currentStart = Long.MIN_VALUE;
private int currentCount;
private int previousCount;
public SlidingWindowCounterRateLimiter(int limit, long windowNanos, LongSupplier clock) {
this.limit = limit;
this.windowNanos = windowNanos;
this.clock = clock;
}
@Override
public synchronized Decision tryAcquire() {
long now = clock.getAsLong();
long start = Math.floorDiv(now, windowNanos) * windowNanos;
if (start != currentStart) {
// moved exactly one window on -> current becomes previous; further on -> previous is empty
previousCount = (start - currentStart == windowNanos) ? currentCount : 0;
currentCount = 0;
currentStart = start;
}
double overlap = 1.0 - (double) (now - currentStart) / windowNanos;
double estimate = previousCount * overlap + currentCount;
if (estimate + 1 <= limit) {
currentCount++;
return Decision.permitted();
}
return Decision.denied(currentStart + windowNanos - now);
}
}
@@ -0,0 +1,36 @@
package com.ankurm.interviewlab.ratelimiter;
import java.util.ArrayDeque;
import java.util.function.LongSupplier;
/**
* Sliding window log: remember the timestamp of every accepted request, forget those older than the
* window, accept if fewer than {@code limit} remain. Exact - no boundary burst - but memory is
* O(limit) per key, which hurts when limit is large and keys are many.
*/
public final class SlidingWindowLogRateLimiter implements RateLimiter {
private final int limit;
private final long windowNanos;
private final LongSupplier clock;
private final ArrayDeque<Long> accepted = new ArrayDeque<>();
public SlidingWindowLogRateLimiter(int limit, long windowNanos, LongSupplier clock) {
this.limit = limit;
this.windowNanos = windowNanos;
this.clock = clock;
}
@Override
public synchronized Decision tryAcquire() {
long now = clock.getAsLong();
while (!accepted.isEmpty() && accepted.peekFirst() <= now - windowNanos) {
accepted.pollFirst();
}
if (accepted.size() < limit) {
accepted.addLast(now);
return Decision.permitted();
}
return Decision.denied(accepted.peekFirst() + windowNanos - now);
}
}
@@ -0,0 +1,38 @@
package com.ankurm.interviewlab.ratelimiter;
import java.util.function.LongSupplier;
/**
* Token bucket, lock-based. The bucket holds up to {@code capacity} tokens and refills continuously at
* {@code refillPerSecond}; each request spends one. A full bucket lets a burst of {@code capacity}
* through, then traffic settles to the refill rate - which is why most public APIs use it.
*/
public final class TokenBucketRateLimiter implements RateLimiter {
private final double capacity;
private final double refillPerNano;
private final LongSupplier clock;
private double tokens;
private long lastRefill;
public TokenBucketRateLimiter(int capacity, double refillPerSecond, LongSupplier clock) {
this.capacity = capacity;
this.refillPerNano = refillPerSecond / 1_000_000_000.0;
this.clock = clock;
this.tokens = capacity;
this.lastRefill = clock.getAsLong();
}
@Override
public synchronized Decision tryAcquire() {
long now = clock.getAsLong();
tokens = Math.min(capacity, tokens + (now - lastRefill) * refillPerNano);
lastRefill = now;
if (tokens >= 1.0) {
tokens -= 1.0;
return Decision.permitted();
}
return Decision.denied((long) Math.ceil((1.0 - tokens) / refillPerNano));
}
}
@@ -0,0 +1,34 @@
package com.ankurm.interviewlab.ratelimiter.redis;
import com.ankurm.interviewlab.ratelimiter.Decision;
import com.ankurm.interviewlab.ratelimiter.RateLimiter;
import redis.clients.jedis.UnifiedJedis;
/**
* The tempting wrong answer: GET the counter, compare in Java, then INCR. Each command is atomic,
* the sequence is not - many threads (or app instances) read "9", all decide 9 &lt; 10, all INCR.
* Kept in the repo only so RedisRaceDemo can show the overshoot. Do not copy it.
*/
public final class NaiveRedisRateLimiter implements RateLimiter {
private final UnifiedJedis jedis;
private final String key;
private final int limit;
public NaiveRedisRateLimiter(UnifiedJedis jedis, String key, int limit) {
this.jedis = jedis;
this.key = key;
this.limit = limit;
}
@Override
public Decision tryAcquire() {
String current = jedis.get(key);
long count = current == null ? 0 : Long.parseLong(current);
if (count < limit) {
jedis.incr(key);
return Decision.permitted();
}
return Decision.denied(1_000_000_000L);
}
}
@@ -0,0 +1,54 @@
package com.ankurm.interviewlab.ratelimiter.redis;
import com.ankurm.interviewlab.ratelimiter.RateLimiter;
import redis.clients.jedis.RedisClient;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.atomic.AtomicInteger;
/**
* 200 threads hit one Redis key at the same instant; the limit is 10. Needs a Redis on localhost:6391
* (scripts/run-redis-demo.sh starts one). The naive count varies from run to run; the Lua count does not.
*/
public final class RedisRaceDemo {
public static void main(String[] args) throws Exception {
int port = args.length > 0 ? Integer.parseInt(args[0]) : 6391;
try (RedisClient jedis = RedisClient.create("localhost", port)) {
jedis.flushAll();
System.out.println("Limit 10. 200 threads, one request each, released at the same instant.");
System.out.println();
for (int run = 1; run <= 5; run++) {
jedis.flushAll();
int naive = race(new NaiveRedisRateLimiter(jedis, "naive", 10));
jedis.flushAll();
int lua = race(new RedisTokenBucketRateLimiter(jedis, "lua", 10, 0.1));
System.out.printf("run %d: naive GET+INCR allowed %2d | Lua token bucket allowed %2d%n", run, naive, lua);
}
}
}
private static int race(RateLimiter limiter) throws Exception {
int threads = 200;
CountDownLatch ready = new CountDownLatch(threads);
CountDownLatch go = new CountDownLatch(1);
AtomicInteger allowed = new AtomicInteger();
try (ExecutorService pool = Executors.newFixedThreadPool(threads)) {
for (int i = 0; i < threads; i++) {
pool.submit(() -> {
ready.countDown();
go.await();
if (limiter.tryAcquire().allowed()) {
allowed.incrementAndGet();
}
return null;
});
}
ready.await();
go.countDown();
}
return allowed.get();
}
}
@@ -0,0 +1,50 @@
package com.ankurm.interviewlab.ratelimiter.redis;
import com.ankurm.interviewlab.ratelimiter.Decision;
import com.ankurm.interviewlab.ratelimiter.RateLimiter;
import redis.clients.jedis.UnifiedJedis;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.concurrent.TimeUnit;
/**
* Distributed token bucket: the bucket lives in Redis, so every app instance that uses the same key
* shares one quota. All of read-refill-spend-write happens inside one Lua script, and Redis runs one
* script at a time, so there is no window for two instances to read the same balance.
*/
public final class RedisTokenBucketRateLimiter implements RateLimiter {
private final UnifiedJedis jedis;
private final String key;
private final String script;
private final int capacity;
private final double refillPerSecond;
public RedisTokenBucketRateLimiter(UnifiedJedis jedis, String key, int capacity, double refillPerSecond) {
this.jedis = jedis;
this.key = key;
this.capacity = capacity;
this.refillPerSecond = refillPerSecond;
this.script = loadScript();
}
@Override
public Decision tryAcquire() {
Object raw = jedis.eval(script, List.of(key), List.of(Integer.toString(capacity), Double.toString(refillPerSecond)));
List<?> reply = (List<?>) raw;
boolean allowed = ((Long) reply.get(0)) == 1L;
long retryMs = (Long) reply.get(1);
return allowed ? Decision.permitted() : Decision.denied(TimeUnit.MILLISECONDS.toNanos(retryMs));
}
private static String loadScript() {
try (var in = RedisTokenBucketRateLimiter.class.getResourceAsStream("/token_bucket.lua")) {
return new String(in.readAllBytes(), StandardCharsets.UTF_8);
} catch (IOException e) {
throw new UncheckedIOException(e);
}
}
}
@@ -0,0 +1,38 @@
package com.ankurm.interviewlab.ratelimiter.web;
import com.ankurm.interviewlab.ratelimiter.Decision;
import com.ankurm.interviewlab.ratelimiter.KeyedRateLimiter;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.web.servlet.HandlerInterceptor;
/**
* Runs before every controller method. Picks a key (X-Client-Id header if present, otherwise the
* caller's address), asks the limiter, and either lets the request continue or answers 429 itself
* with a Retry-After header. Returning false stops the request before the controller runs.
*/
public final class RateLimitInterceptor implements HandlerInterceptor {
private final KeyedRateLimiter limiter;
public RateLimitInterceptor(KeyedRateLimiter limiter) {
this.limiter = limiter;
}
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
String key = request.getHeader("X-Client-Id");
if (key == null || key.isBlank()) {
key = request.getRemoteAddr();
}
Decision decision = limiter.tryAcquire(key);
if (decision.allowed()) {
return true;
}
response.setStatus(429);
response.setHeader("Retry-After", Long.toString(decision.retryAfterSeconds()));
response.setContentType("text/plain");
response.getWriter().write("Too Many Requests - retry after " + decision.retryAfterSeconds() + "s\n");
return false;
}
}
@@ -0,0 +1,41 @@
package com.ankurm.interviewlab.ratelimiter.web;
import com.ankurm.interviewlab.ratelimiter.KeyedRateLimiter;
import com.ankurm.interviewlab.ratelimiter.LockFreeTokenBucketRateLimiter;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
/**
* Smallest useful Spring Boot wiring: bucket of 5, refilling 1 token every 2 seconds, per client.
* Registered for /api/** only, so health checks and static files are never limited.
*/
@SpringBootApplication
public class RateLimitedApp implements WebMvcConfigurer {
public static void main(String[] args) {
SpringApplication.run(RateLimitedApp.class, args);
}
@Bean
KeyedRateLimiter keyedRateLimiter() {
return new KeyedRateLimiter(() -> new LockFreeTokenBucketRateLimiter(5, 0.5, System::nanoTime));
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(new RateLimitInterceptor(keyedRateLimiter())).addPathPatterns("/api/**");
}
@RestController
static class HelloController {
@GetMapping("/api/hello")
String hello() {
return "hello\n";
}
}
}
@@ -0,0 +1,36 @@
-- Token bucket as ONE atomic Redis operation.
-- KEYS[1] bucket key
-- ARGV[1] capacity (tokens)
-- ARGV[2] refill rate (tokens per second)
-- Returns {allowed (1/0), retry_after_ms}
-- Time comes from Redis (TIME), not from the caller, so app servers with skewed clocks cannot
-- disagree about how many tokens have refilled.
local t = redis.call('TIME')
local now_ms = t[1] * 1000 + math.floor(t[2] / 1000)
local capacity = tonumber(ARGV[1])
local rate = tonumber(ARGV[2])
local data = redis.call('HMGET', KEYS[1], 'tokens', 'ts')
local tokens = tonumber(data[1])
local ts = tonumber(data[2])
if tokens == nil then
tokens = capacity
ts = now_ms
end
tokens = math.min(capacity, tokens + math.max(0, now_ms - ts) * rate / 1000)
local allowed = 0
local retry_ms = 0
if tokens >= 1 then
tokens = tokens - 1
allowed = 1
else
retry_ms = math.ceil((1 - tokens) / rate * 1000)
end
redis.call('HSET', KEYS[1], 'tokens', tostring(tokens), 'ts', now_ms)
-- an idle bucket is a full bucket, so it can be forgotten after one full refill (+ margin)
redis.call('PEXPIRE', KEYS[1], math.ceil(capacity / rate * 1000) + 1000)
return {allowed, retry_ms}
@@ -0,0 +1,95 @@
package com.ankurm.interviewlab.ratelimiter;
import org.junit.jupiter.api.Test;
import java.time.Duration;
import java.util.function.Function;
import java.util.function.LongSupplier;
import static org.junit.jupiter.api.Assertions.*;
class AlgorithmBehaviourTest {
private static final long WINDOW = Duration.ofSeconds(10).toNanos();
private static int burst(RateLimiter limiter, int n) {
int ok = 0;
for (int i = 0; i < n; i++) {
if (limiter.tryAcquire().allowed()) ok++;
}
return ok;
}
private static int totalAcrossBoundary(Function<LongSupplier, RateLimiter> factory) {
ManualClock clock = new ManualClock();
RateLimiter limiter = factory.apply(clock);
clock.set(Duration.ofSeconds(9));
int first = burst(limiter, 5);
clock.set(Duration.ofSeconds(11));
return first + burst(limiter, 5);
}
@Test
void fixedWindowAllowsDoubleTheLimitAcrossABoundary() {
assertEquals(10, totalAcrossBoundary(c -> new FixedWindowRateLimiter(5, WINDOW, c)));
}
@Test
void slidingLogNeverExceedsLimitInAnyWindow() {
assertEquals(5, totalAcrossBoundary(c -> new SlidingWindowLogRateLimiter(5, WINDOW, c)));
}
@Test
void slidingCounterNeverExceedsLimitAcrossTheBoundary() {
assertEquals(5, totalAcrossBoundary(c -> new SlidingWindowCounterRateLimiter(5, WINDOW, c)));
}
@Test
void tokenBucketAllowsBurstThenRefillRate() {
ManualClock clock = new ManualClock();
TokenBucketRateLimiter bucket = new TokenBucketRateLimiter(5, 0.5, clock); // 1 token per 2s
assertEquals(5, burst(bucket, 8));
clock.advance(Duration.ofSeconds(2));
assertEquals(1, burst(bucket, 3));
clock.advance(Duration.ofSeconds(100));
assertEquals(5, burst(bucket, 8), "an idle bucket refills to capacity, never beyond");
}
@Test
void lockFreeBucketBehavesLikeLockedBucket() {
ManualClock a = new ManualClock();
ManualClock b = new ManualClock();
RateLimiter locked = new TokenBucketRateLimiter(5, 0.5, a);
RateLimiter free = new LockFreeTokenBucketRateLimiter(5, 0.5, b);
for (int second = 0; second < 30; second++) {
assertEquals(burst(locked, 2), burst(free, 2), "second " + second);
a.advance(Duration.ofSeconds(1));
b.advance(Duration.ofSeconds(1));
}
}
@Test
void deniedDecisionTellsWhenToRetry() {
ManualClock clock = new ManualClock();
TokenBucketRateLimiter bucket = new TokenBucketRateLimiter(1, 0.5, clock);
assertTrue(bucket.tryAcquire().allowed());
Decision denied = bucket.tryAcquire();
assertFalse(denied.allowed());
assertEquals(2, denied.retryAfterSeconds());
FixedWindowRateLimiter fixed = new FixedWindowRateLimiter(1, WINDOW, new ManualClock());
fixed.tryAcquire();
assertEquals(10, fixed.tryAcquire().retryAfterSeconds());
}
@Test
void keyedLimiterGivesEachKeyItsOwnQuota() {
ManualClock clock = new ManualClock();
KeyedRateLimiter keyed = new KeyedRateLimiter(() -> new FixedWindowRateLimiter(2, WINDOW, clock));
assertTrue(keyed.tryAcquire("alice").allowed());
assertTrue(keyed.tryAcquire("alice").allowed());
assertFalse(keyed.tryAcquire("alice").allowed());
assertTrue(keyed.tryAcquire("bob").allowed(), "bob is unaffected by alice");
assertEquals(2, keyed.trackedKeys());
}
}
@@ -0,0 +1,57 @@
package com.ankurm.interviewlab.ratelimiter;
import org.junit.jupiter.api.Test;
import java.time.Duration;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.function.Function;
import java.util.function.LongSupplier;
import static org.junit.jupiter.api.Assertions.assertEquals;
/**
* 64 threads x 100 attempts each against a limiter whose clock never moves. Exactly {@code limit}
* attempts may succeed - not limit+1, not limit-1 - whichever algorithm is behind the interface.
*/
class ConcurrencyTest {
private static final int LIMIT = 50;
private static final long WINDOW = Duration.ofSeconds(10).toNanos();
private static int hammer(RateLimiter limiter) throws Exception {
int threads = 64;
CountDownLatch ready = new CountDownLatch(threads);
CountDownLatch go = new CountDownLatch(1);
AtomicInteger allowed = new AtomicInteger();
try (ExecutorService pool = Executors.newFixedThreadPool(threads)) {
for (int t = 0; t < threads; t++) {
pool.submit(() -> {
ready.countDown();
go.await();
for (int i = 0; i < 100; i++) {
if (limiter.tryAcquire().allowed()) allowed.incrementAndGet();
}
return null;
});
}
ready.await();
go.countDown();
}
return allowed.get();
}
private static void check(Function<LongSupplier, RateLimiter> factory) throws Exception {
for (int round = 0; round < 5; round++) {
assertEquals(LIMIT, hammer(factory.apply(new ManualClock())), "round " + round);
}
}
@Test void fixedWindow() throws Exception { check(c -> new FixedWindowRateLimiter(LIMIT, WINDOW, c)); }
@Test void slidingLog() throws Exception { check(c -> new SlidingWindowLogRateLimiter(LIMIT, WINDOW, c)); }
@Test void slidingCounter() throws Exception { check(c -> new SlidingWindowCounterRateLimiter(LIMIT, WINDOW, c)); }
@Test void tokenBucket() throws Exception { check(c -> new TokenBucketRateLimiter(LIMIT, 1, c)); }
@Test void lockFreeBucket() throws Exception { check(c -> new LockFreeTokenBucketRateLimiter(LIMIT, 1, c)); }
}
@@ -0,0 +1,96 @@
package com.ankurm.interviewlab.ratelimiter.redis;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import redis.clients.jedis.RedisClient;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicInteger;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assumptions.assumeTrue;
/** Starts its own redis-server on port 6392 (skipped, not failed, when the binary is absent). */
class RedisLimiterTest {
private static final int PORT = 6392;
private static Process redis;
@BeforeAll
static void startRedis() throws Exception {
try {
redis = new ProcessBuilder("redis-server", "--port", Integer.toString(PORT), "--save", "", "--appendonly", "no")
.redirectErrorStream(true).redirectOutput(ProcessBuilder.Redirect.DISCARD).start();
} catch (java.io.IOException e) {
assumeTrue(false, "redis-server not installed");
}
for (int i = 0; i < 50; i++) {
try (RedisClient j = RedisClient.create("localhost", PORT)) {
if ("PONG".equals(j.ping())) return;
} catch (Exception ignored) {
Thread.sleep(100);
}
}
throw new IllegalStateException("redis did not start");
}
@AfterAll
static void stopRedis() {
if (redis != null) redis.destroy();
}
private static int race(List<RedisTokenBucketRateLimiter> instances, int attempts) throws Exception {
CountDownLatch go = new CountDownLatch(1);
AtomicInteger allowed = new AtomicInteger();
List<Future<?>> futures = new ArrayList<>();
try (ExecutorService pool = Executors.newFixedThreadPool(attempts)) {
for (int i = 0; i < attempts; i++) {
RedisTokenBucketRateLimiter limiter = instances.get(i % instances.size());
futures.add(pool.submit(() -> {
go.await();
if (limiter.tryAcquire().allowed()) allowed.incrementAndGet();
return null;
}));
}
go.countDown();
for (Future<?> f : futures) f.get();
}
return allowed.get();
}
@Test
void luaBucketAdmitsExactlyCapacityUnderRace() throws Exception {
try (RedisClient jedis = RedisClient.create("localhost", PORT)) {
for (int round = 0; round < 5; round++) {
jedis.flushAll();
var limiter = new RedisTokenBucketRateLimiter(jedis, "race", 10, 0.1);
assertEquals(10, race(List.of(limiter), 50), "round " + round);
}
}
}
@Test
void twoAppInstancesShareOneQuota() throws Exception {
try (RedisClient instanceA = RedisClient.create("localhost", PORT);
RedisClient instanceB = RedisClient.create("localhost", PORT)) {
instanceA.flushAll();
var a = new RedisTokenBucketRateLimiter(instanceA, "shared", 10, 0.1);
var b = new RedisTokenBucketRateLimiter(instanceB, "shared", 10, 0.1);
assertEquals(10, race(List.of(a, b), 50), "two separate clients, one shared bucket");
}
}
@Test
void idleBucketExpiresInRedis() throws Exception {
try (RedisClient jedis = RedisClient.create("localhost", PORT)) {
jedis.flushAll();
new RedisTokenBucketRateLimiter(jedis, "ttl", 10, 0.1).tryAcquire();
long ttlMs = jedis.pttl("ttl");
// capacity/rate = 100s, plus the 1s margin
assertEquals(true, ttlMs > 90_000 && ttlMs <= 101_000, "ttl was " + ttlMs);
}
}
}
@@ -0,0 +1,55 @@
package com.ankurm.interviewlab.ratelimiter.web;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import org.springframework.boot.SpringApplication;
import org.springframework.context.ConfigurableApplicationContext;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import static org.junit.jupiter.api.Assertions.*;
class RateLimitedAppTest {
private static ConfigurableApplicationContext ctx;
private static int port;
private static final HttpClient HTTP = HttpClient.newHttpClient();
@BeforeAll
static void start() {
ctx = SpringApplication.run(RateLimitedApp.class, "--server.port=0", "--spring.main.banner-mode=off");
port = Integer.parseInt(ctx.getEnvironment().getProperty("local.server.port"));
}
@AfterAll
static void stop() {
ctx.close();
}
private static HttpResponse<String> get(String clientId) throws Exception {
HttpRequest req = HttpRequest.newBuilder(URI.create("http://localhost:" + port + "/api/hello"))
.header("X-Client-Id", clientId).build();
return HTTP.send(req, HttpResponse.BodyHandlers.ofString());
}
@Test
void sixthRequestGets429WithRetryAfter() throws Exception {
for (int i = 1; i <= 5; i++) {
assertEquals(200, get("alice").statusCode(), "request " + i);
}
HttpResponse<String> sixth = get("alice");
assertEquals(429, sixth.statusCode());
assertEquals("2", sixth.headers().firstValue("Retry-After").orElseThrow());
}
@Test
void otherClientsAreUnaffected() throws Exception {
for (int i = 0; i < 6; i++) get("carol");
assertEquals(429, get("carol").statusCode());
assertEquals(200, get("dave").statusCode());
}
}