What is the Rate Limiting Library?

The Rate Limiting Library is an open-source, production-grade rate limiting solution for Java applications. It provides annotation-based API protection with sub-millisecond overhead, supporting Spring Boot and Quarkus frameworks.

How do I add rate limiting to my Spring Boot application?

Simply add the rl-adapter-spring dependency to your pom.xml and use the @RateLimit annotation on your controller methods. For example: @RateLimit(requests = 100, window = 60) limits to 100 requests per 60 seconds.

What rate limiting algorithms are supported?

The library supports Token Bucket (for burst handling) and Sliding Window (for accuracy) algorithms. Token Bucket allows controlled bursts while maintaining average rates, while Sliding Window provides smooth, accurate rate limiting without boundary issues.

Does it support distributed rate limiting with Redis?

Yes, the library includes Redis support with atomic Lua scripts for consistent rate limiting across multiple application instances. It also features L1/L2 tiered storage with automatic failover for high availability.

What is the performance overhead?

Local storage (Caffeine) has P99 latency under 100 microseconds with over 3 million operations per second. Distributed storage (Redis) has P99 latency under 2 milliseconds with approximately 40,000 operations per second.

Rate Limiting Library | Production-Grade Java Rate Limiter for Spring Boot & Quarkus

Why This Library

Built for Real Production

Designed with production patterns in mind. Clean architecture. Extensible by design.

Blazing Fast

Sub-millisecond decisions won't slow your hot paths. O(1) algorithms, lock-free data structures, and zero allocations in the critical path.

One Line Setup

Add @RateLimit and you're done. No XML configs, no boilerplate, no ceremony. Works instantly with Spring Boot and Quarkus.

Scales Horizontally

Redis backend with atomic Lua scripts ensures consistent limits across your entire cluster. No double-counting, no race conditions.

Fails Gracefully

Redis down? Circuit breakers kick in. Tiered L1/L2 storage keeps your app running. Designed for the chaos of production.

Security First

SpEL injection attacks? Blocked. Key enumeration? Prevented. PII in logs? Masked. We sweat the security details so you don't have to.

Full Visibility

Prometheus metrics out of the box. Know exactly who's hitting limits, what's being blocked, and when to adjust your quotas.

Architecture

Use Only What You Need

Modular by design. Small JARs. No bloat. Mix and match for your stack.

Module	What It Does	Size
rl-core	The engine: algorithms, resilience, security. Zero dependencies.	~10.8K LOC
rl-spi-redis	Distributed storage. Atomic Lua scripts. Cluster-ready.	~770 LOC
rl-spi-caffeine	In-memory storage. Blazing fast. Great for single-instance.	~800 LOC
rl-adapter-spring	Drop-in for Spring Boot. Auto-config. AOP magic included.	~2.7K LOC
rl-adapter-quarkus	Native Quarkus support. CDI interceptors. GraalVM ready.	~800 LOC

Quick Start

Two Steps. That's It.

Add the dependency. Add the annotation. Your API is protected.

1. Add Dependency (pom.xml)

<dependency>
    <groupId>com.lycosoft</groupId>
    <artifactId>rl-adapter-spring</artifactId>
    <version>0.1.0-beta.1</version>
</dependency>

2. Use the Annotation

@RestController
public class OrderController {

    // Allow 100 requests per 60 seconds
    @RateLimit(requests = 100, window = 60)
    @GetMapping("/orders")
    public List<Order> getOrders() {
        return orderService.findAll();
    }
}

Spring Boot Documentation Developer Guide

1. Add Dependency (pom.xml)

<dependency>
    <groupId>com.lycosoft</groupId>
    <artifactId>rl-adapter-quarkus</artifactId>
    <version>0.1.0-beta.1</version>
</dependency>

2. Use the Annotation

@Path("/orders")
public class OrderResource {

    // Allow 100 requests per 60 seconds
    @RateLimit(requests = 100, window = 60)
    @GET
    public List<Order> getOrders() {
        return orderService.findAll();
    }
}

Quarkus Documentation Developer Guide

Real-World Patterns

Beyond the Basics

Powerful enough for complex scenarios. Simple enough to understand.

Limit by User

Use SpEL expressions to rate limit per authenticated user.

@RateLimit(
    key = "#user.id",
    requests = 100,
    window = 60
)
@PostMapping("/api/orders")
public Order createOrder(
    @AuthenticationPrincipal User user,
    @RequestBody OrderRequest request
) {
    return orderService.create(request);
}

Multi-Tenant Apps

Combine tenant + user for SaaS-style fair usage limits.

@RateLimit(
    key = "#tenant.id + ':' + #user.id",
    requests = 50,
    window = 60
)
public void tenantAction() { ... }

Burst Protection + Quotas

Stack multiple limits: prevent sudden spikes AND enforce long-term quotas.

@RateLimits({
    @RateLimit(name = "burst", requests = 10, window = 1),       // 10 req/sec max
    @RateLimit(name = "hourly", requests = 1000, window = 3600)  // 1000 req/hour quota
})
@GetMapping("/api/resource")
public Resource getResource() {
    return resourceService.fetch();
}

Optional Tuning

Works out of the box. Fine-tune when you need to.

ratelimit:
  enabled: true
  storage: redis          # or: caffeine
  spel:
    compiler-mode: IMMEDIATE
    cache-size: 1000

Built-in Metrics

Prometheus-ready. Alert on abuse before it becomes a problem.

# Who's getting blocked?
rate(ratelimit_denied_total[5m])

# How much traffic is allowed?
sum(rate(ratelimit_allowed_total[5m]))

Documentation

Comprehensive Guides

Everything you need to implement rate limiting in your application.

Developer Guide

Complete reference for all features, algorithms, and YAML configuration options.

Read Guide

Spring Boot Guide

Annotation-driven rate limiting with auto-configuration for Spring Boot applications.

Read Guide

Quarkus Guide

CDI interceptors with reactive support and native compilation compatibility.

Read Guide

Standalone Guide

Use the core library directly in any Java application without frameworks.

Read Guide

Stop Bad Traffic.
Ship Faster.

Built for Real Production

Blazing Fast

One Line Setup

Scales Horizontally

Fails Gracefully

Security First

Full Visibility

Use Only What You Need

Two Steps. That's It.

Beyond the Basics

Limit by User

Multi-Tenant Apps

Burst Protection + Quotas

Optional Tuning

Built-in Metrics

Comprehensive Guides

Developer Guide

Spring Boot Guide

Quarkus Guide

Standalone Guide

Ready to Protect Your APIs?