Rate Limiting

Regius includes a powerful rate limiting middleware to protect your application from abuse and DDoS attacks.

Features

• Two Algorithms: Token Bucket and Sliding Window
• Multiple Storage Backends: In-memory, Redis, and Badger
• Configurable Limits: Set requests per time window
• IP Whitelisting: Exclude specific IPs from rate limiting
• Proxy Support: Trust X-Forwarded-For and X-Real-IP headers
• Standard HTTP Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Window, Retry-After
• Per-path Rate Limiting: Each route path gets its own rate limit
• Flexible Application: Apply globally or to specific routes

Algorithms

Token Bucket Algorithm

Best for steady request patterns. Tokens are added to a bucket at a fixed rate, and each request consumes a token.

Sliding Window Algorithm

More accurate for burst traffic. Tracks requests within a sliding time window.

Configuration

config := regius.RateLimiterConfig{
    Enabled:    true,
    Algorithm:  regius.RateLimiterAlgorithmSlidingWindow,
    Requests:   100,
    Window:     time.Minute,
    Storage:    "",
    TrustProxy: true,
    Whitelist:  []string{"127.0.0.1", "::1"},
}

Configuration Options

Option	Type	Description
Enabled	bool	Enable/disable rate limiting
Algorithm	string	"token_bucket" or "sliding_window"
Requests	int	Maximum requests per window
Window	duration	Time duration (time.Second, time.Minute, time.Hour)
Storage	string	"" for in-memory, "redis" or "badger"
TrustProxy	bool	Trust proxy headers (X-Forwarded-For, X-Real-IP)
Whitelist	[]string	IPs to exclude from rate limiting

Usage

Apply Globally

Apply rate limiting to all routes:

// In regius-app/routes.go
a.use(a.Middleware.RateLimit)

Apply to API Routes

Apply rate limiting to API routes only:

// In regius-app/routes-api.go
r.Use(a.Middleware.APIRateLimit)

Apply to Specific Routes

Apply strict rate limiting to specific routes:

r.Post("/login", a.Middleware.RateLimitStrict(a.Handlers.Login))

Storage Backends

In-Memory Storage (Default)

Fastest option, but not distributed. Rate limits are local to each instance.

Storage: ""

Redis Storage

Distributed storage for multiple instances. Configure Redis in your .env file.

Storage: "redis"

Required .env settings:

REDIS_HOST=localhost:6379
REDIS_PASSWORD=
REDIS_PREFIX=myapp

Badger Storage

Embedded distributed storage.

Storage: "badger"

HTTP Headers

The rate limiter adds the following headers to responses:

• X-RateLimit-Limit: Maximum requests allowed in the time window
• X-RateLimit-Remaining: Number of requests remaining in the window
• X-RateLimit-Window: Time window in seconds
• Retry-After: Seconds until the next request will be allowed (when rate limited)

Testing

The skeleton app includes comprehensive testing tools in the test-tools/ directory:

• ratelimit-test.py - Python-based tester with detailed output
• ratelimit-test.sh - Shell script using curl
• ratelimit-tester.go - Go-based high-performance tester

For more details on testing, see the Rate Limiter Testing Guide.

Best Practices

1. Start with In-Memory: Use in-memory storage for development
2. Choose the Right Algorithm: Use Token Bucket for steady traffic, Sliding Window for bursty traffic
3. Whitelist Trusted IPs: Add internal IPs and monitoring services to the whitelist
4. Monitor and Adjust: Monitor your rate limit headers and adjust limits based on traffic patterns
5. Differentiate Routes: Use stricter limits for auth endpoints and more lenient limits for public content