🛡️ SurgeShield (surgeshield)

📌 Overview

✨ Key Features

🏗️ System Architecture

🚀 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)

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

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

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

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

[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)

📁 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