Distributed Rate Limiter v1.2.0

Distributed Rate Limiter v1.2.0 - Release Notes

🎉 Major Feature Release - October 23, 2025

🌟 Highlights

This release brings four major new features to the Distributed Rate Limiter, significantly expanding its capabilities for modern cloud-native applications:

1. 🎨 Interactive Web Dashboard - Real-time monitoring and management UI
2. 🚰 Leaky Bucket Algorithm - Traffic shaping for constant output rates
3. 🔄 Composite Rate Limiting - Multi-algorithm composition
4. 🌍 Geographic Rate Limiting - Location-aware rate limits with compliance support

📊 Release Statistics

• 46 commits since v1.1.0
• 5 total algorithms (Token Bucket, Sliding Window, Fixed Window, Leaky Bucket, Composite)
• 20+ new React components for web dashboard
• 6 comprehensive screenshots showcasing features
• 4 Architecture Decision Records documenting design decisions
• Maintained >85% test coverage with extensive new tests

---

🎨 Interactive Web Dashboard

A modern, production-ready React dashboard for monitoring and managing your distributed rate limiter in real-time.

Key Features

• 📊 Live Monitoring: Real-time metrics with 5-second polling from backend

  • System metrics: requests/second, token usage, active keys
  • Algorithm distribution visualization
  • Recent activity feed with allow/deny status
  • Trend charts for request rates and token consumption

• 🧪 Load Testing: Production-grade benchmarking interface

  • Configure concurrent requests, duration, key patterns
  • Real-time progress with success/failure rates
  • Latency percentiles (P50, P95, P99)
  • Connected to backend /api/benchmark/run endpoint

• ⚙️ Configuration Management: Dynamic CRUD operations

  • Global, per-key, and pattern-based configuration
  • Algorithm selection (Token Bucket, Sliding Window, Fixed Window, Leaky Bucket, Composite)
  • Live updates via REST API
  • Hierarchical configuration visualization

• 🔑 API Keys Management: Centralized key tracking

  • Auto-discovery from /admin/keys endpoint
  • Token counts, capacity, refill rates
  • Reset operations (individual or bulk)
  • Algorithm assignments per key

• 📈 Analytics & Trends: Historical insights (demo/preview)

  • Time-series visualization
  • Top keys analysis
  • Geographic distribution
  • Compliance reporting
  • Note: Requires time-series database backend (InfluxDB, Prometheus, TimescaleDB) for production use

• 🧮 Algorithm Comparison: Interactive educational tool

  • Side-by-side algorithm simulations
  • Real-time parameter adjustments
  • Use case guidance and performance comparison
  • Client-side educational demonstrations

Tech Stack

• React 18 + TypeScript
• Vite for blazing-fast builds
• Tailwind CSS + shadcn/ui components
• Recharts for data visualization
• Fully responsive and mobile-friendly

Quick Start

# Terminal 1: Start backend
./mvnw spring-boot:run

# Terminal 2: Start dashboard
cd examples/web-dashboard
npm install && npm run dev
# Open http://localhost:5173

Screenshots

All dashboard pages are documented with high-quality screenshots in:

• examples/web-dashboard/public/screenshots/
• Main README with complete feature descriptions

---

🚰 Leaky Bucket Algorithm

New rate limiting algorithm optimized for traffic shaping and constant output rates.

Characteristics

• Queue-based Processing: Requests queue and process at constant rate
• No Bursts: Enforces strict, predictable output rate
• Downstream Protection: Ideal for protecting backend services
• SLA Compliance: Guaranteed maximum throughput

Use Cases

• Database connection pool protection
• Third-party API call rate limiting
• Network-like traffic shaping
• Downstream service protection (payment processors, email services)
• Constant throughput enforcement

Implementation

• Local: LeakyBucket.java for in-memory
• Distributed: RedisLeakyBucket.java with atomic Lua scripts
• Performance: Comparable to Token Bucket with stricter rate enforcement
• Memory: Similar to Token Bucket, tracks queue state

Configuration Example

curl -X POST http://localhost:8080/api/ratelimit/config/keys/db:connection_pool \
  -H "Content-Type: application/json" \
  -d '{
    "capacity": 20,
    "refillRate": 5,
    "algorithm": "LEAKY_BUCKET"
  }'

Documentation

• ADR-004: Complete design rationale and algorithm analysis
• Examples: cURL, Java, Python, Node.js, Go integration examples
• API Docs: Updated with Leaky Bucket parameter specifications

---

🔄 Composite Rate Limiting

Enterprise-grade multi-algorithm composition for complex rate limiting scenarios.

Features

• Multi-Algorithm Support: Combine Token Bucket, Sliding Window, Fixed Window, Leaky Bucket

• 5 Combination Logic Types:

  1. ALL_MUST_PASS - AND operation (all components must allow)
  2. ANY_CAN_PASS - OR operation (any component allows)
  3. WEIGHTED_AVERAGE - Score-based with configurable weights
  4. HIERARCHICAL_AND - Scope-ordered evaluation (USER → TENANT → GLOBAL)
  5. PRIORITY_BASED - High-priority first, fail-fast evaluation

• Scope Support: USER, TENANT, GLOBAL, API, BANDWIDTH

• Component-Level Results: Detailed breakdown of each algorithm's decision

• Weights & Priorities: Fine-grained control over algorithm importance

Use Cases

• SaaS Platforms: API calls + bandwidth + compliance limits simultaneously
• Financial Systems: Rate + volume + velocity checks
• Gaming Platforms: Actions + chat messages + resource consumption
• IoT Systems: Commands + data transfer + connection limits
• Multi-Tenant Applications: User-level + tenant-level + global limits

Configuration Example

curl -X POST http://localhost:8080/api/ratelimit/check \
  -H "Content-Type: application/json" \
  -d '{
    "key": "enterprise:customer:123",
    "tokens": 1,
    "algorithm": "COMPOSITE",
    "compositeConfig": {
      "limits": [
        {
          "name": "api_calls",
          "algorithm": "TOKEN_BUCKET",
          "capacity": 10000,
          "refillRate": 1000,
          "scope": "API",
          "weight": 1.0,
          "priority": 1
        },
        {
          "name": "bandwidth",
          "algorithm": "LEAKY_BUCKET",
          "capacity": 100,
          "refillRate": 50,
          "scope": "BANDWIDTH",
          "weight": 1.0,
          "priority": 2
        }
      ],
      "combinationLogic": "ALL_MUST_PASS"
    }
  }'

Enhanced Response

{
  "allowed": false,
  "componentResults": {
    "api_calls": {
      "allowed": false,
      "currentTokens": 0,
      "capacity": 10000
    },
    "bandwidth": {
      "allowed": true,
      "currentTokens": 45,
      "capacity": 100
    }
  },
  "limitingComponent": "api_calls",
  "combinationResult": {
    "logic": "ALL_MUST_PASS",
    "overallScore": 0.0,
    "componentScores": {
      "api_calls": 0.0,
      "bandwidth": 1.0
    }
  }
}

Documentation

• ADR-005: Architecture decision record with design rationale
• Examples: Complete integration examples in examples/composite-rate-limiting.md
• API Docs: Detailed parameter specifications and response schemas

---

🌍 Geographic Rate Limiting

Location-aware rate limiting with automatic compliance zone detection.

Features

• Multi-CDN Support: CloudFlare, AWS CloudFront, Azure CDN headers
• Compliance Zones: Automatic GDPR, CCPA, PIPEDA detection
• Country/Region Rules: Flexible geographic rule configuration
• Priority-Based Matching: Configurable rule precedence
• Fallback Logic: Graceful degradation when location unknown
• Performance: <2ms additional latency for geolocation

Use Cases

• Regulatory Compliance: Different rate limits for GDPR vs non-GDPR regions
• Regional Traffic Management: Higher limits for premium regions
• DDoS Protection: Stricter limits for high-risk countries
• Cost Optimization: Lower limits for expensive CDN regions
• A/B Testing: Regional rollouts with different rate limits

CDN Header Support

# CloudFlare headers
curl -X POST http://localhost:8080/api/ratelimit/check \
  -H "CF-IPCountry: DE" \
  -H "CF-IPContinent: EU" \
  -H "Content-Type: application/json" \
  -d '{"key": "api:user:123", "tokens": 1}'

# AWS CloudFront headers
curl -X POST http://localhost:8080/api/ratelimit/check \
  -H "CloudFront-Viewer-Country: US" \
  -H "Content-Type: application/json" \
  -d '{"key": "api:user:456", "tokens": 1}'

Geographic Rule Management

# Add GDPR compliance rule
curl -X POST http://localhost:8080/api/ratelimit/geographic/rules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "eu-gdpr-compliance",
    "complianceZone": "GDPR",
    "keyPattern": "api:*",
    "limits": {"capacity": 500, "refillRate": 50},
    "priority": 100
  }'

# List all geographic rules
curl http://localhost:8080/api/ratelimit/geographic/rules

# Get detection stats
curl http://localhost:8080/api/ratelimit/geographic/stats

Response with Geographic Info

{
  "allowed": true,
  "geoInfo": {
    "detectedCountry": "Germany",
    "complianceZone": "GDPR",
    "appliedRule": "geo:DE:GDPR",
    "appliedLimits": {
      "capacity": 500,
      "refillRate": 50
    }
  }
}

Documentation

• Complete Guide: docs/GEOGRAPHIC_RATE_LIMITING.md
• API Endpoints: 4 new REST endpoints for geographic management
• Examples: Integration with all major CDN providers

---

🔧 Additional Improvements

CORS Support for Web Dashboard

• Global CORS configuration in WebCorsConfiguration.java
• Support for localhost:3000, localhost:5173, 127.0.0.1, IPv6
• Comprehensive header allowlist
• Credential support and preflight caching

Code Modernization

• Replaced wildcard imports with specific imports (cleaner codebase)
• Modernized test mocking to use @TestConfiguration
• Updated to modern Spring Data Redis API patterns
• Replaced deprecated test assertion methods
• Locale-independent toString implementations
• Improved API parameter handling with comprehensive model tests

CI/CD Fixes

• Fixed Redis connection pool test for CI/CD environments
• Resolved ConcurrentPerformanceTest.testEndurance stability
• Added missing service mocks for composite rate limiting
• Made geographic components conditional to prevent test failures

Frontend Improvements

• Resolved CORS issues between frontend and backend
• Synchronized TypeScript models with backend Java DTOs
• Fixed Configuration page data loading
• Added proxy routes for /admin and /metrics
• Removed mock data generators (now uses real backend APIs)
• Enhanced error handling and loading states

---

📦 Download & Installation

JAR File (Recommended)

# Download
wget https://github.com/uppnrise/distributed-rate-limiter/releases/download/v1.2.0/distributed-rate-limiter-1.2.0.jar

# Run
java -jar distributed-rate-limiter-1.2.0.jar

Docker

docker run -p 8080:8080 ghcr.io/uppnrise/distributed-rate-limiter:1.2.0

Build from Source

git clone https://github.com/uppnrise/distributed-rate-limiter.git
cd distributed-rate-limiter
git checkout v1.2.0
./mvnw clean install
java -jar target/distributed-rate-limiter-1.2.0.jar

---

📊 Performance

Maintained Benchmarks

• Throughput: 50,000+ requests/second (unchanged)
• Latency: P95 < 2ms, P99 < 5ms (unchanged)
• Memory: ~100MB for 1M active buckets
• CPU: <5% under normal load
• Geographic Overhead: <2ms additional latency

Algorithm Performance Comparison

Algorithm	Memory Efficiency	Burst Handling	Accuracy	Use Case
Token Bucket	Moderate	Excellent	Good	General APIs
Sliding Window	Moderate	Good	Excellent	Critical APIs
Fixed Window	High	Moderate	Good	High-scale
Leaky Bucket	Moderate	None	Excellent	Traffic shaping
Composite	Low	Varies	Excellent	Enterprise

---

🔄 Migration Guide

From v1.1.0 to v1.2.0

All changes are backward compatible - no breaking changes.

1. Web Dashboard (Optional):

   cd examples/web-dashboard
   npm install
   npm run dev

2. New Algorithms (Opt-in):

   # Continue using default Token Bucket, or configure explicitly
   ratelimiter.algorithm=LEAKY_BUCKET  # or COMPOSITE

3. Geographic Rate Limiting (Opt-in):

   • Add CDN headers to requests
   • Configure geographic rules via REST API
   • Falls back to default behavior if no location detected

4. Composite Rate Limiting (Explicit configuration required):

   • Use compositeConfig in API requests
   • Specify combination logic and component limits

Configuration Compatibility

• All existing application.properties configurations continue to work
• Per-key and pattern-based configurations remain unchanged
• Default algorithm is still Token Bucket (no changes required)

---

🐛 Known Issues

None at release time.

---

🚀 What's Next (v1.3.0)

Potential future enhancements:

• Time-Series Database Integration: Real historical analytics
• Advanced Metrics Dashboard: Grafana/Prometheus dashboards
• Additional Algorithms: Token Bucket with penalty, Redis GCRA
• Enhanced Geographic Features: IP geolocation database integration
• WebSocket Support: Real-time dashboard updates
• gRPC API: Alternative to REST for high-performance scenarios

---

📚 Complete Documentation

• Main README: Project overview and quick start
• CHANGELOG: Detailed change history
• API Documentation: Complete REST API reference at /swagger-ui/index.html
• Web Dashboard README: examples/web-dashboard/README.md
• Architecture Decision Records: docs/adr/ directory
• Client Examples: Java, Python, Node.js, Go, cURL
• Deployment Guides: Docker, Kubernetes, production setup

---

🙏 Acknowledgments

This release includes contributions from automated testing, CI/CD improvements, and comprehensive documentation updates. Special thanks to the open-source community for feedback and issue reports.

---

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details.

---

🆘 Support

• Documentation: Complete guides in the repository
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Examples: docs/examples/ and examples/ directories

---

🎉 Enjoy the new features in v1.2.0!

⭐ Star this project if you find it useful!