Middleware Package

HTTP middleware collection for Gin framework providing cross-cutting concerns like rate limiting, CSRF protection, and request handling.

---

Overview

The pkg/middleware package contains reusable HTTP middleware components that can be applied to routes or route groups in the Gin web framework. These middleware handle security, rate limiting, and other cross-cutting concerns.

---

Available Middleware

1. Rate Limiter

IP-based rate limiting using token bucket algorithm to prevent abuse and brute-force attacks.

Key Features:

• Per-IP rate limiting with token bucket algorithm
• Configurable rate and burst size
• Thread-safe with RWMutex
• Automatic cleanup of old limiters
• X-RateLimit-* headers (Limit, Remaining, Reset)

Usage:

import (
    "github.com/basilex/promenade/pkg/middleware"
    "golang.org/x/time/rate"
)

// Create rate limiter: 5 requests per minute with burst of 1
loginLimiter := middleware.NewRateLimiter(rate.Every(time.Minute/5), 1)

// Apply to routes
router.POST("/auth/login", loginLimiter.Limit(), loginHandler)
router.POST("/auth/register", registerLimiter.Limit(), registerHandler)

Common Rate Configurations:

// 5 requests per minute (authentication endpoints)
rate.Every(time.Minute/5), 1

// 3 requests per minute (registration)
rate.Every(time.Minute/3), 1

// 100 requests per minute (general API)
rate.Limit(100/60), 10

Response Headers:

• X-RateLimit-Limit - Maximum requests per window
• X-RateLimit-Remaining - Remaining requests in current window
• X-RateLimit-Reset - Unix timestamp when limit resets

HTTP Status:

• 429 Too Many Requests - Rate limit exceeded

See: docs/guides/rate-limiting.md

---

2. CSRF Protection

Cross-Site Request Forgery (CSRF) protection middleware with double-submit cookie pattern.

Key Features:

• Double-submit cookie pattern (stateless)
• Automatic token generation and validation
• Configurable cookie settings (Secure, HTTPOnly, SameSite)
• Skip safe methods (GET, HEAD, OPTIONS)
• Custom error handling
• SPA-friendly (token exposed via header and cookie)

Usage:

import "github.com/basilex/promenade/pkg/middleware"

// Production configuration
csrfConfig := middleware.DefaultCSRFConfig()
csrfConfig.CookieSecure = true  // HTTPS only
csrfConfig.CookieSameSite = http.SameSiteStrictMode

csrfMiddleware := middleware.CSRFMiddleware(csrfConfig)

// Apply to protected routes
protected := router.Group("/api")
protected.Use(csrfMiddleware)
{
    protected.POST("/users", createUserHandler)
    protected.PUT("/users/:id", updateUserHandler)
    protected.DELETE("/users/:id", deleteUserHandler)
}

Client Integration:

// 1. Frontend reads token from cookie
const csrfToken = document.cookie
    .split('; ')
    .find(row => row.startsWith('csrf_token='))
    ?.split('=')[1];

// 2. Include in requests
fetch('/api/users', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-CSRF-Token': csrfToken
    },
    body: JSON.stringify(userData)
});

Configuration Options:

type CSRFConfig struct {
    TokenLength     int           // Token length in bytes (default: 32)
    CookieName      string        // Cookie name (default: "csrf_token")
    HeaderName      string        // Header name (default: "X-CSRF-Token")
    CookieMaxAge    int           // Max age in seconds (default: 12 hours)
    CookiePath      string        // Cookie path (default: "/")
    CookieDomain    string        // Cookie domain (default: "")
    CookieSecure    bool          // HTTPS only (default: true in prod)
    CookieHTTPOnly  bool          // HTTP only (default: true)
    CookieSameSite  http.SameSite // SameSite attribute (default: Strict)
    SkipMethods     []string      // Skip methods (default: GET, HEAD, OPTIONS)
    ErrorHandler    func(*gin.Context) // Custom error handler
}

HTTP Status:

• 403 Forbidden - CSRF token missing or invalid

See: docs/guides/csrf-protection.md

---

Testing

Run Tests

# All middleware tests
go test ./pkg/middleware -v

# Rate limiter tests
go test ./pkg/middleware -run TestRateLimiter -v

# CSRF tests
go test ./pkg/middleware -run TestCSRF -v

# With coverage
go test ./pkg/middleware -cover

Test Statistics

Component	Tests	Coverage	Status
Rate Limiter	10	95%
CSRF	15	92%
Total	25	93%

---

Best Practices

Rate Limiting

DO:

• Apply rate limiting to authentication endpoints (login, register)
• Use stricter limits for password reset and sensitive operations
• Return proper X-RateLimit-* headers
• Clean up old limiters periodically (built-in)

DON'T:

• Don't apply rate limiting to static assets
• Don't use same limiter for all endpoints (create separate instances)
• Don't ignore rate limit errors in production

CSRF Protection

DO:

• Enable CSRF for all state-changing operations (POST, PUT, DELETE, PATCH)
• Use CookieSecure=true in production (HTTPS only)
• Set SameSite=Strict or Lax for additional protection
• Skip CSRF for public APIs that use token authentication
• Implement proper error handling on client side

DON'T:

• Don't disable CSRF in production without JWT/OAuth
• Don't use CSRF alone without HTTPS
• Don't set CookieHTTPOnly=false (exposes token to XSS)
• Don't skip CSRF validation on authenticated routes

---

Architecture

Rate Limiter Flow

   Request   

        1. Extract IP address
       

  RateLimiter.Limit()                
  - Get or create limiter for IP     
  - Check if request allowed         

        2. Check token bucket
       

  rate.Limiter.Allow()               
  - Token bucket algorithm           

       
        Allowed → Continue to handler
       
        Denied → 429 Too Many Requests

CSRF Flow

   Browser   

        1. First request (any method)
       

  CSRF Middleware                    
  - Generate token                   
  - Set cookie with token            
  - Set header X-CSRF-Token          

        2. Cookie + Header returned
       

   Browser    Stores cookie, reads header

        3. POST/PUT/DELETE request
           Cookie: csrf_token=...
           X-CSRF-Token: ...
       

  CSRF Middleware                    
  - Extract token from header        
  - Extract token from cookie        
  - Compare tokens                   

       
        Match → Continue to handler
       
        Mismatch → 403 Forbidden

---

Integration Examples

Basic API Setup

func setupRouter(cfg *config.AppConfig) *gin.Engine {
    router := gin.New()
    
    // Rate limiters
    loginLimiter := middleware.NewRateLimiter(rate.Every(time.Minute/5), 1)
    registerLimiter := middleware.NewRateLimiter(rate.Every(time.Minute/3), 1)
    apiLimiter := middleware.NewRateLimiter(rate.Limit(100/60), 10)
    
    // CSRF config
    csrfConfig := middleware.DefaultCSRFConfig()
    csrfConfig.CookieSecure = cfg.App.Environment == "production"
    csrfMiddleware := middleware.CSRFMiddleware(csrfConfig)
    
    // Public routes with rate limiting
    auth := router.Group("/auth")
    {
        auth.POST("/login", loginLimiter.Limit(), loginHandler)
        auth.POST("/register", registerLimiter.Limit(), registerHandler)
    }
    
    // Protected API with CSRF + rate limiting
    api := router.Group("/api")
    api.Use(jwtMiddleware)
    api.Use(csrfMiddleware)
    api.Use(apiLimiter.Limit())
    {
        api.POST("/users", createUserHandler)
        api.PUT("/users/:id", updateUserHandler)
        api.DELETE("/users/:id", deleteUserHandler)
    }
    
    return router
}

Multi-Tenant Rate Limiting

// Different rate limits per endpoint
type RateLimiters struct {
    Auth     *middleware.RateLimiter
    API      *middleware.RateLimiter
    Admin    *middleware.RateLimiter
}

func NewRateLimiters() *RateLimiters {
    return &RateLimiters{
        Auth:  middleware.NewRateLimiter(rate.Every(time.Minute/5), 1),
        API:   middleware.NewRateLimiter(rate.Limit(100/60), 10),
        Admin: middleware.NewRateLimiter(rate.Limit(1000/60), 100),
    }
}

---

Security Considerations

Rate Limiting

1. IP Spoofing: Use X-Forwarded-For carefully, validate trusted proxies
2. Distributed Attacks: Consider distributed rate limiting with Redis
3. Resource Exhaustion: Implement cleanup to prevent memory leaks (built-in)
4. Bypass Attempts: Log rate limit violations for monitoring

CSRF Protection

1. Token Entropy: Default 32-byte tokens = 256-bit security (secure)
2. Cookie Security: Always use Secure + HTTPOnly + SameSite in production
3. Token Rotation: Tokens rotate on each request (stateless)
4. XSS Mitigation: CSRF alone doesn't prevent XSS, combine with CSP headers
5. Subdomain Attacks: Set CookieDomain carefully for multi-domain setups

---

Performance

Rate Limiter

• Memory: ~100 bytes per IP address
• Throughput: ~10M requests/sec (token bucket check)
• Cleanup: Automatic periodic cleanup of unused limiters
• Concurrency: Thread-safe with RWMutex (read-heavy optimization)

CSRF

• Overhead: ~1-2ms per request (token generation + validation)
• Memory: Stateless (no server-side storage)
• Token Size: 43 bytes (base64-encoded 32-byte token)
• Cookie Size: ~100 bytes total

---

Future Enhancements

Planned Features

• [ ] Redis-based rate limiting - Distributed rate limiting across instances
• [ ] Rate limit policies - Named policies for different endpoint types
• [ ] Token bucket variations - Sliding window, fixed window
• [ ] CORS middleware - Cross-origin resource sharing
• [ ] Request ID middleware - Trace request through system
• [ ] Compression middleware - Gzip response compression
• [ ] Circuit breaker - Prevent cascading failures

---

Related Documentation

• Rate Limiting Guide
• CSRF Protection Guide
• JWT Middleware
• Testing Guide
• Main README

---

Last Updated: December 31, 2025
Status: Production-ready
Test Coverage: 25 tests, 93% coverage
Maintainer: Promenade Team