🛡️ SurgeShield (surgeshield)

A high-performance, asynchronous, lock-free rate limiter library, Redis distributed cluster store, dynamic IP blacklisting engine ("The Jail"), zero-downtime TOML hot-reloader, Prometheus exporter, and Tower/Axum middleware built in Rust.

---

📌 Overview

SurgeShield is an enterprise-grade rate limiting engine, distributed cluster store, automated DDoS defense system, and real-time 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, Dynamic IP Blacklisting ("The Jail"), Zero-Downtime TOML Hot-Reloading, 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 with sub-millisecond latency.
• 🚫 Dynamic IP Blacklisting ("The Jail"): Automatically detects clients with repeated 429 Too Many Requests violations and jails them with instant 403 Forbidden responses (< 0.01ms overhead, bypassing token bucket evaluations).
• 🔄 Zero-Downtime Hot-Reloading (surgeshield.toml): Background file watcher reloads rate limits and jail rules live at runtime without restarting the server.
• 🌐 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 (200), blocked (429), and jailed (403) traffic breakdown, with an interactive 60 FPS Cyber Matrix background grid.
• 📊 Prometheus Metrics Exporter (GET /metrics): Exposes standard OpenMetrics format:
  • surgeshield_requests_allowed_total (counter)
  • surgeshield_requests_blocked_total (counter for 429 status)
  • surgeshield_requests_jailed_total (counter for 403 status)
  • surgeshield_active_keys (gauge)
  • surgeshield_evaluation_duration_seconds (histogram)
• 🐳 Docker Ready (ghcr.io): Lightweight multi-stage container deployment published to GitHub Container Registry.
• 🤖 Automated GitHub Actions CI/CD: Matrix builds across Linux, Windows, and macOS with inline Clippy PR code review annotations and daily RustSec dependency security audits.

---

🏗️ System Architecture

graph TD
    Client[📱 Client Request] --> MW[🛡️ SurgeShield Middleware Layer]
    MW --> JailCheck{🚫 Check Jail Status}
    
    JailCheck -->|Jailed / Banned| FastReject[⛔ Instant 403 Forbidden - < 0.01ms]
    FastReject --> Client
    
    JailCheck -->|Not Jailed| KeyExt[🔑 Key Extractor]
    KeyExt --> Metrics[📊 Record Prometheus Telemetry]
    
    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]

    Reject --> JailMgr[🚫 Increment Violation Counter]
    JailMgr -->|≥ 5 Violations| JailTrigger[🔒 Place Client in Jail - 60s]

    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 jailStyle fill:#d97706,stroke:#b45309,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,FastReject rejectStyle;
    class JailCheck,JailMgr,JailTrigger jailStyle;
    class Metrics,Prometheus,MetricsEndpoint,UI obsStyle;

Loading

---

🚀 Quick Start

1. Basic In-Memory Rate Limiting with Jail Protection

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();

    // 5 request burst capacity, refills 1 token/sec + default Jail (5 429s -> 60s ban)
    let store = MemoryStore::new_token_bucket(5, 1.0);
    let rate_limiter = RateLimiterLayer::new(store, KeyExtractor::ClientIp).with_default_jail();

    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 Distributed Cluster (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).with_default_jail();

    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();
}

---

🐳 Docker Deployment

Run SurgeShield instantly using Docker:

docker run -d --name surgeshield -p 3000:3000 ghcr.io/8ernity/surgeshield:latest

Or build locally:

docker build -t surgeshield .
docker run -p 3000:3000 surgeshield

---

🔄 Zero-Downtime Hot-Reloading (surgeshield.toml)

Edit surgeshield.toml while the server is running to update limits live without server restarts:

[rate_limiter]
capacity = 10
refill_rate_per_sec = 2.0

[jail]
enabled = true
max_violations = 5
ban_duration_secs = 60

---

🖥️ Live Telemetry Dashboard (GET /dashboard)

Open http://localhost:3000/dashboard in your browser:

• Live Request Counters: Real-time counter for Allowed (200), Blocked (429), and Jailed (403) requests.
• Refractive Liquid Glass Panels: 100% crystal-clear backdrop refraction with specular 3D edge lighting.
• Interactive Cyber Matrix Grid: High-density 60 FPS matrix background responding to cursor proximity.
• Throughput Charts: Chart.js lines plotting allowed, blocked, and jailed traffic per second.

---

📁 Repository Structure

surgeshield/
├── Cargo.toml               # Project manifest & dependencies
├── Dockerfile               # Multi-stage container build
├── .dockerignore            # Docker build exclusions
├── surgeshield.toml         # Hot-reloadable runtime configuration
├── README.md                # Project documentation
├── .github/
│   └── workflows/
│       ├── ci.yml           # Multi-OS matrix CI with inline Clippy annotations
│       ├── audit.yml        # Daily RustSec dependency security audit
│       └── docker.yml       # Automated GitHub Container Registry publisher
├── 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, SurgeShieldConfig & ConfigHandle watcher
│   ├── jail.rs              # Thread-safe lock-free JailManager & IP blacklisting
│   ├── 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 server with Redis, Jail & Hot-Reloading
└── 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