🛡️ SurgeShield (surgeshield)

A high-performance, asynchronous, lock-free rate limiter library, Redis distributed store, Prometheus exporter, and Tower/Axum middleware built in Rust.

---

📌 Overview

SurgeShield is an invisible, production-ready rate limiting engine, distributed cluster store, and observability stack designed for high-concurrency web services, microservices, and API gateways in Rust. It protects web applications against denial-of-service (DoS) attacks, brute-force exploits, and sudden traffic spikes without introducing garbage collection delays or global locks.

By combining DashMap lock-free in-memory storage, Redis atomic Lua distributed storage, Prometheus OpenMetrics telemetry, an embedded live visual Web Dashboard, and Tokio's async runtime, SurgeShield delivers sub-millisecond rate limit decisions and real-time cluster observability.

---

✨ Key Features

• 🚀 High Throughput & Lock-Free State: Built on DashMap for concurrent, non-blocking evaluation across all CPU cores.
• 🌐 Distributed Redis Storage (RedisStore): Share atomic rate limit quotas across multiple cloud server nodes or Kubernetes pods using Redis and atomic Lua scripting.
• 🧮 Dual Rate Limiting Engines:
  • Token Bucket Algorithm: Perfect for bursty traffic with smooth floating-point token replenishment.
  • Sliding Window Counter: Eliminates window-boundary burst exploits using weighted window estimation.
• 🖥️ Embedded Live Telemetry Dashboard (GET /dashboard): Zero-dependency, single-page dark-mode Web UI featuring real-time Chart.js graphs showing live RPS, allowed/blocked traffic breakdown, and evaluation latency.
• 📊 Prometheus Metrics Exporter (GET /metrics): Exposes standard OpenMetrics format:
  • surgeshield_requests_allowed_total (counter)
  • surgeshield_requests_blocked_total (counter for 429 status)
  • surgeshield_active_keys (gauge)
  • surgeshield_evaluation_duration_seconds (histogram)
• 📉 1-Click Grafana Template: Pre-built dashboards/grafana_surgeshield.json dashboard configuration ready for instant Grafana import.
• 🔑 Flexible Key Extraction Strategies: Client IP (X-Forwarded-For, X-Real-IP), HTTP Headers (Authorization, X-API-Key), Route URI Path, and Composite keys.
• 🧹 Automated Background TTL Eviction: Spawns a background worker (tokio::spawn) to sweep and purge inactive client states, preventing OOM memory leaks.
• 🌐 Seamless Tower / Axum Middleware: Integrates natively as a Tower::Layer in Axum, Hyper, or any Tower-compatible service stack.
• 📜 Standards-Compliant HTTP Headers: Automatically injects X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After headers.

---

🏗️ System Architecture

graph TD
    Client[📱 Client Request] --> MW[🛡️ SurgeShield Middleware Layer]
    MW --> Metrics[📊 Record Prometheus Telemetry]
    MW --> KeyExt[🔑 Key Extractor]
    
    KeyExt -->|Single-Instance Node| MemStore[💾 MemoryStore / DashMap]
    KeyExt -->|Multi-Node Cluster| RedisStore[⚡ RedisStore / Atomic Lua]
    
    MemStore --> Engine{🧮 Rate Limit Engine}
    RedisStore --> Engine
    
    Engine -->|Quota Available| Pass[✅ Allow Request - 200 OK]
    Engine -->|Quota Exceeded| Reject[⛔ Block Request - 429 Rate Limited]

    Pass --> AppRoute[🚀 Application Route Handler]
    Reject --> Client

    Prometheus[🔥 Prometheus Server] -->|Scrapes GET /metrics| MetricsEndpoint[📈 Prometheus Endpoint /metrics]
    Browser[🌐 Web Browser] -->|Views GET /dashboard| UI[🖥️ Embedded Telemetry Web UI]

    classDef clientStyle fill:#2563eb,stroke:#1d4ed8,stroke-width:2px,color:#ffffff;
    classDef mwStyle fill:#7c3aed,stroke:#6d28d9,stroke-width:2px,color:#ffffff;
    classDef storeStyle fill:#0284c7,stroke:#0369a1,stroke-width:2px,color:#ffffff;
    classDef engineStyle fill:#d97706,stroke:#b45309,stroke-width:2px,color:#ffffff;
    classDef passStyle fill:#059669,stroke:#047857,stroke-width:2px,color:#ffffff;
    classDef rejectStyle fill:#dc2626,stroke:#b91c1c,stroke-width:2px,color:#ffffff;
    classDef obsStyle fill:#0891b2,stroke:#0e7490,stroke-width:2px,color:#ffffff;

    class Client,Browser clientStyle;
    class MW,KeyExt mwStyle;
    class MemStore,RedisStore storeStyle;
    class Engine engineStyle;
    class Pass,AppRoute passStyle;
    class Reject rejectStyle;
    class Metrics,Prometheus,MetricsEndpoint,UI obsStyle;

Loading

---

🚀 Quick Start

1. In-Memory Rate Limiting

use axum::{routing::get, Json, Router};
use rust_rate_limiter::{
    config::KeyExtractor,
    init_prometheus,
    middleware::RateLimiterLayer,
    render_dashboard,
    store::MemoryStore,
};
use serde_json::{json, Value};

#[tokio::main]
async fn main() {
    let prometheus_handle = init_prometheus().unwrap();

    // In-memory store: 5 request burst capacity, refills 1 token/sec
    let store = MemoryStore::new_token_bucket(5, 1.0);
    let rate_limiter = RateLimiterLayer::new(store, KeyExtractor::ClientIp);

    let app = Router::new()
        .route("/api/data", get(|| async { Json(json!({"status": "success"})) }))
        .layer(rate_limiter)
        .route("/metrics", get(move || async move { prometheus_handle.render() }))
        .route("/dashboard", get(render_dashboard));

    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

2. Multi-Node Cluster Rate Limiting (RedisStore)

For Kubernetes pods or load-balanced cloud nodes, use RedisStore to share the exact same rate limit quota across all instances:

use rust_rate_limiter::{RedisStore, RateLimiterLayer, KeyExtractor};
use axum::{Router, routing::get};

#[tokio::main]
async fn main() {
    // Distributed Redis Store: 100 requests burst capacity, refills 10 tokens/sec
    let redis_store = RedisStore::new("redis://127.0.0.1:6379/", 100, 10.0)
        .await
        .expect("Failed to connect to Redis cluster");

    let rate_limiter = RateLimiterLayer::new(redis_store, KeyExtractor::ClientIp);

    let app = Router::new()
        .route("/api/v1/resource", get(|| async { "Cluster protected resource" }))
        .layer(rate_limiter);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

---

🖥️ Live Embedded Telemetry Dashboard (GET /dashboard)

Open http://localhost:3000/dashboard in any web browser to view the real-time visual UI:

• Live Request Counters: Real-time counter for Allowed (200 OK) vs Blocked (429 Rate Limited) requests.
• Interactive Chart.js Graph: Live line chart plotting throughput trends per second.
• Traffic Breakdown: Doughnut chart showing the percentage of blocked traffic.
• Evaluation Latency: Live microsecond calculation speed metric.

---

📊 Prometheus & Grafana Integration

1. Prometheus Scraping (GET /metrics)

Exposes standard metrics format:

# HELP surgeshield_requests_allowed_total Total number of allowed requests
# TYPE surgeshield_requests_allowed_total counter
surgeshield_requests_allowed_total{key_id="127.0.0.1"} 42

# HELP surgeshield_requests_blocked_total Total number of blocked 429 requests
# TYPE surgeshield_requests_blocked_total counter
surgeshield_requests_blocked_total{key_id="127.0.0.1"} 8

# HELP surgeshield_evaluation_duration_seconds Rate limit evaluation latency in seconds
# TYPE surgeshield_evaluation_duration_seconds summary

2. 1-Click Grafana Dashboard Import

Import dashboards/grafana_surgeshield.json directly into Grafana to get instant visual panels for Allowed vs Blocked RPS, Active Keys Gauge, and Traffic Flow.

---

🧪 Testing

Execute the test suite covering unit math, 100-thread concurrency, and Axum middleware integration:

cargo test

Run the live example server:

cargo run --example axum_server

---

📁 Repository Structure

D:\Projects\rust_rate_limiter/
├── Cargo.toml               # Project manifest & dependencies
├── README.md                # Project documentation
├── .gitignore               # Git build artifact exclusions
├── .vscode/
│   └── settings.json        # VS Code workspace exclusions
├── dashboards/
│   └── grafana_surgeshield.json # 1-Click Grafana dashboard template
├── src/
│   ├── lib.rs               # Main library entry point & exports
│   ├── error.rs             # Custom Error types and Result alias
│   ├── config.rs            # KeyExtractor enum & configuration rules
│   ├── metrics/             # Prometheus telemetry exporter & counters
│   │   └── mod.rs
│   ├── dashboard/           # Embedded HTML/JS visual web dashboard
│   │   └── mod.rs
│   ├── engine/              # Core rate limiter algorithm implementations
│   │   ├── mod.rs           # Engine traits & decision outcome types
│   │   ├── token_bucket.rs  # Token Bucket algorithm
│   │   └── sliding_window.rs# Sliding Window Counter algorithm
│   ├── store/               # Storage layer abstractions
│   │   ├── mod.rs           # RateLimitStore async trait
│   │   ├── memory.rs        # DashMap in-memory store + background TTL worker
│   │   └── redis.rs         # Redis atomic Lua distributed cluster store
│   └── middleware/          # Tower & Axum middleware integration
│       ├── mod.rs           # Tower Layer & Service implementations
│       └── headers.rs       # HTTP header injection logic
├── examples/
│   └── axum_server.rs       # Complete, runnable Axum web server with /metrics & /dashboard
└── tests/
    ├── engine_tests.rs      # Unit tests for algorithms & refill logic
    ├── concurrency_tests.rs # 100-thread multi-threaded stress tests
    └── middleware_tests.rs  # Axum HTTP integration & header tests

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

Crafted with ❤️ and 🦀 Rust by 8ernity