Rate Limiting

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

Features

• Two Algorithms: Token Bucket (steady request patterns) and Sliding Window (accurate for burst traffic)
• Multiple Storage Backends: In-memory (fastest), Redis (distributed), and Badger (embedded distributed)
• Configurable Limits: Set requests per time window (e.g., 100 requests per minute)
• IP Whitelisting: Exclude specific IPs or CIDR ranges (e.g. 10.0.0.0/8, ::1/128) from rate limiting — IPv4 and IPv6 supported
• Proxy Support: Trust X-Forwarded-For (first IP) 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 (API, auth, etc.)

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", "10.0.0.0/8"},
}

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 or CIDR ranges to exclude from rate limiting

Usage

Apply Globally

Apply rate limiting to all routes:

// In routes.go
a.use(a.Middleware.RateLimit)

Apply to API Routes

Apply rate limiting to API routes only:

// In 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"

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

You can exercise the rate limiter with any HTTP load tool (e.g. hey, wrk, or a small curl loop) against a rate-limited route in your app.

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