diff --git a/README.md b/README.md index 9a61ddf..63fadea 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/rate-limiter/.gitignore b/rate-limiter/.gitignore new file mode 100644 index 0000000..2f7896d --- /dev/null +++ b/rate-limiter/.gitignore @@ -0,0 +1 @@ +target/ diff --git a/rate-limiter/README.md b/rate-limiter/README.md new file mode 100644 index 0000000..fd98090 --- /dev/null +++ b/rate-limiter/README.md @@ -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. diff --git a/rate-limiter/pom.xml b/rate-limiter/pom.xml new file mode 100644 index 0000000..3b01194 --- /dev/null +++ b/rate-limiter/pom.xml @@ -0,0 +1,83 @@ + + + 4.0.0 + com.ankurm.interviewlab + rate-limiter + 1.0.0 + jar + + java-interview-lab :: rate-limiter + + 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. + + + + 25 + UTF-8 + 6.1.3 + 4.1.2 + 8.0.2 + + + + + + org.junit + junit-bom + ${junit.version} + pom + import + + + org.springframework.boot + spring-boot-dependencies + ${spring-boot.version} + pom + import + + + + + + + org.springframework.boot + spring-boot-starter-webmvc + + + redis.clients + jedis + ${jedis.version} + + + org.junit.jupiter + junit-jupiter + test + + + org.junit.platform + junit-platform-launcher + test + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.14.0 + + + org.apache.maven.plugins + maven-surefire-plugin + 3.6.0 + + -Xmx512m -Duser.timezone=UTC -Dfile.encoding=UTF-8 + + + + + diff --git a/rate-limiter/scripts/run-demo.sh b/rate-limiter/scripts/run-demo.sh new file mode 100755 index 0000000..7de042b --- /dev/null +++ b/rate-limiter/scripts/run-demo.sh @@ -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' diff --git a/rate-limiter/scripts/run-redis-demo.sh b/rate-limiter/scripts/run-redis-demo.sh new file mode 100755 index 0000000..cdcf473 --- /dev/null +++ b/rate-limiter/scripts/run-redis-demo.sh @@ -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' diff --git a/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/BoundaryBurstDemo.java b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/BoundaryBurstDemo.java new file mode 100644 index 0000000..775fcac --- /dev/null +++ b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/BoundaryBurstDemo.java @@ -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 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; + } +} diff --git a/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/Decision.java b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/Decision.java new file mode 100644 index 0000000..bb1f83d --- /dev/null +++ b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/Decision.java @@ -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)); + } +} diff --git a/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/FixedWindowRateLimiter.java b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/FixedWindowRateLimiter.java new file mode 100644 index 0000000..fd18779 --- /dev/null +++ b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/FixedWindowRateLimiter.java @@ -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); + } +} diff --git a/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/KeyedRateLimiter.java b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/KeyedRateLimiter.java new file mode 100644 index 0000000..76bfa52 --- /dev/null +++ b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/KeyedRateLimiter.java @@ -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 limiters = new ConcurrentHashMap<>(); + private final Supplier factory; + + public KeyedRateLimiter(Supplier factory) { + this.factory = factory; + } + + public Decision tryAcquire(String key) { + return limiters.computeIfAbsent(key, k -> factory.get()).tryAcquire(); + } + + public int trackedKeys() { + return limiters.size(); + } +} diff --git a/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/LockFreeTokenBucketRateLimiter.java b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/LockFreeTokenBucketRateLimiter.java new file mode 100644 index 0000000..0b9650e --- /dev/null +++ b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/LockFreeTokenBucketRateLimiter.java @@ -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; + + 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(); + } + } + } +} diff --git a/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/ManualClock.java b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/ManualClock.java new file mode 100644 index 0000000..9af0208 --- /dev/null +++ b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/ManualClock.java @@ -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()); + } +} diff --git a/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/RateLimiter.java b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/RateLimiter.java new file mode 100644 index 0000000..cc1b280 --- /dev/null +++ b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/RateLimiter.java @@ -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(); +} diff --git a/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/SlidingWindowCounterRateLimiter.java b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/SlidingWindowCounterRateLimiter.java new file mode 100644 index 0000000..f0f86fa --- /dev/null +++ b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/SlidingWindowCounterRateLimiter.java @@ -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); + } +} diff --git a/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/SlidingWindowLogRateLimiter.java b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/SlidingWindowLogRateLimiter.java new file mode 100644 index 0000000..521f69c --- /dev/null +++ b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/SlidingWindowLogRateLimiter.java @@ -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 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); + } +} diff --git a/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/TokenBucketRateLimiter.java b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/TokenBucketRateLimiter.java new file mode 100644 index 0000000..0a5bbf4 --- /dev/null +++ b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/TokenBucketRateLimiter.java @@ -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)); + } +} diff --git a/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/redis/NaiveRedisRateLimiter.java b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/redis/NaiveRedisRateLimiter.java new file mode 100644 index 0000000..ee04c79 --- /dev/null +++ b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/redis/NaiveRedisRateLimiter.java @@ -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 < 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); + } +} diff --git a/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/redis/RedisRaceDemo.java b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/redis/RedisRaceDemo.java new file mode 100644 index 0000000..771e1bd --- /dev/null +++ b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/redis/RedisRaceDemo.java @@ -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(); + } +} diff --git a/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/redis/RedisTokenBucketRateLimiter.java b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/redis/RedisTokenBucketRateLimiter.java new file mode 100644 index 0000000..7e1125f --- /dev/null +++ b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/redis/RedisTokenBucketRateLimiter.java @@ -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); + } + } +} diff --git a/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/web/RateLimitInterceptor.java b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/web/RateLimitInterceptor.java new file mode 100644 index 0000000..4eb0e49 --- /dev/null +++ b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/web/RateLimitInterceptor.java @@ -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; + } +} diff --git a/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/web/RateLimitedApp.java b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/web/RateLimitedApp.java new file mode 100644 index 0000000..b9becb6 --- /dev/null +++ b/rate-limiter/src/main/java/com/ankurm/interviewlab/ratelimiter/web/RateLimitedApp.java @@ -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"; + } + } +} diff --git a/rate-limiter/src/main/resources/token_bucket.lua b/rate-limiter/src/main/resources/token_bucket.lua new file mode 100644 index 0000000..34752cd --- /dev/null +++ b/rate-limiter/src/main/resources/token_bucket.lua @@ -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} diff --git a/rate-limiter/src/test/java/com/ankurm/interviewlab/ratelimiter/AlgorithmBehaviourTest.java b/rate-limiter/src/test/java/com/ankurm/interviewlab/ratelimiter/AlgorithmBehaviourTest.java new file mode 100644 index 0000000..3b46467 --- /dev/null +++ b/rate-limiter/src/test/java/com/ankurm/interviewlab/ratelimiter/AlgorithmBehaviourTest.java @@ -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 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()); + } +} diff --git a/rate-limiter/src/test/java/com/ankurm/interviewlab/ratelimiter/ConcurrencyTest.java b/rate-limiter/src/test/java/com/ankurm/interviewlab/ratelimiter/ConcurrencyTest.java new file mode 100644 index 0000000..67cc380 --- /dev/null +++ b/rate-limiter/src/test/java/com/ankurm/interviewlab/ratelimiter/ConcurrencyTest.java @@ -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 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)); } +} diff --git a/rate-limiter/src/test/java/com/ankurm/interviewlab/ratelimiter/redis/RedisLimiterTest.java b/rate-limiter/src/test/java/com/ankurm/interviewlab/ratelimiter/redis/RedisLimiterTest.java new file mode 100644 index 0000000..c41e988 --- /dev/null +++ b/rate-limiter/src/test/java/com/ankurm/interviewlab/ratelimiter/redis/RedisLimiterTest.java @@ -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 instances, int attempts) throws Exception { + CountDownLatch go = new CountDownLatch(1); + AtomicInteger allowed = new AtomicInteger(); + List> 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); + } + } +} diff --git a/rate-limiter/src/test/java/com/ankurm/interviewlab/ratelimiter/web/RateLimitedAppTest.java b/rate-limiter/src/test/java/com/ankurm/interviewlab/ratelimiter/web/RateLimitedAppTest.java new file mode 100644 index 0000000..1e3fc0e --- /dev/null +++ b/rate-limiter/src/test/java/com/ankurm/interviewlab/ratelimiter/web/RateLimitedAppTest.java @@ -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 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 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()); + } +}