Skip to content

v0.1.0 — Initial Release (Spring Boot 3 & Java 21)

Latest
Latest

Choose a tag to compare

View all tags
@onizukaTP onizukaTP released this 29 Jul 10:37
v0.1.0
420b889

🚀 Limitly v0.1.0 Initial Release

I am excited to announce the first public release of Limitly (io.github.onizukatp:redis-rate-limiter-spring-boot-starter), a production-ready Spring Boot starter for Redis-backed distributed rate limiting.

Limitly is designed to make rate limiting simple, scalable, and reliable. With an annotation-first API, atomic Redis Lua execution, multiple rate-limiting algorithms, and built-in observability, it provides a drop-in solution for protecting APIs and microservices with minimal configuration.

✨ Highlights

  • Annotation-First API – Protect any endpoint with a single @RateLimit annotation.

  • Distributed & Atomic – Uses Redis Lua scripts to guarantee atomic execution across multiple application instances.

  • Multiple Algorithms

    • Sliding Window Log – Exact request counting using Redis Sorted Sets.
    • Token Bucket – Efficient continuous refill with burst tolerance and a low Redis memory footprint.

  • Flexible Key Resolution

    • USER – Resolves authenticated users or the X-User-ID header.
    • IP – Resolves the real client IP with X-Forwarded-For awareness.
    • SPEL – Supports dynamic Spring Expression Language (SpEL) expressions such as #request.remoteAddr or #user.id.

  • Resilient Fallback Modes

    • FAIL_OPEN (Default) – Allows requests when Redis is unavailable.
    • FAIL_CLOSED – Blocks requests during Redis outages for stricter security.

  • Built-in Observability

    • Native Micrometer metrics
    • Redis latency tracking
    • Request allow/deny counters
    • Redis failure monitoring

  • Automatic HTTP Headers

    • X-RateLimit-Limit
    • X-RateLimit-Remaining
    • Retry-After

🚀 Why Limitly?

Limitly is built with production environments in mind:

  • ✅ Zero-configuration Spring Boot starter
  • ✅ Annotation-based developer experience
  • ✅ Distributed-safe rate limiting
  • ✅ Redis-backed atomic operations
  • ✅ Native Micrometer integration
  • ✅ Flexible key resolution strategies
  • ✅ Lightweight and easy to integrate
  • ✅ Suitable for REST APIs and microservices

✅ Compatibility

  • Java 17+
  • Spring Boot 3.x
  • Redis 6+

⚙️ Default Behavior

Out of the box, Limitly is configured with sensible defaults:

  • Algorithm: SLIDING_WINDOW
  • Key Resolver: USER
  • Fallback Mode: FAIL_OPEN
  • HTTP Status: 429 Too Many Requests
  • Micrometer Metrics: Enabled

This means most applications can start using distributed rate limiting without additional configuration.

📦 Installation

Add the starter dependency to your pom.xml:

<dependency>
    <groupId>io.github.onizukatp</groupId>
    <artifactId>redis-rate-limiter-spring-boot-starter</artifactId>
    <version>0.1.0</version>
</dependency>

⚙️ Quick Configuration

rate-limiter:
  enabled: true
  default-strategy: SLIDING_WINDOW
  default-key-resolver: USER
  fallback-mode: FAIL_OPEN

  redis:
    key-prefix: "ratelimit:"

  response:
    status: 429
    body: '{"error":"rate_limit_exceeded","message":"Too many requests. Please try again later."}'
    include-retry-after-header: true

  metrics:
    enabled: true

💻 Example Usage

@RestController
@RequestMapping("/api")
public class ApiController {

    // Allow 5 requests every 10 seconds using Sliding Window Log
    @GetMapping("/search")
    @RateLimit(limit = 5, window = "10s", strategy = Algorithm.SLIDING_WINDOW)
    public ResponseEntity<?> search(@RequestParam String query) {
        return ResponseEntity.ok(Map.of("query", query));
    }
}

📊 Built-in Metrics

Limitly automatically publishes Micrometer metrics for monitoring and dashboards:

  • ratelimiter.requests.allowed
  • ratelimiter.requests.denied
  • ratelimiter.redis.latency
  • ratelimiter.redis.failures

These metrics integrate seamlessly with Prometheus, Grafana, and other Micrometer-compatible monitoring systems.

📚 Documentation

For detailed configuration, advanced examples, and API reference, see USAGE_GUIDE.md:

https://github.com/onizukaTP/limitly/blob/master/USAGE_GUIDE.md

🛣 Roadmap

Future releases are planned to include:

  • Additional key resolver implementations
  • Custom rate-limiting strategies
  • Enhanced Redis Cluster support
  • Runtime configuration improvements
  • More comprehensive integration tests
  • Expanded documentation and examples

❤️ Feedback & Contributions

Limitly is an open-source project, and feedback is always appreciated. If you encounter a bug, have a feature request, or would like to contribute, feel free to open an issue or submit a pull request.

If you find Limitly useful, consider giving the repository a ⭐ on GitHub—it helps the project reach more developers.

Thank you for trying Limitly.

— Tharun Prabu

Assets 2
Loading