limited

Limited - DynamoDB-based Rate Limiting for Go

Limited is a flexible, high-performance rate limiting library for Go that uses AWS DynamoDB as its backend storage. It supports multiple rate limiting strategies and provides atomic operations for distributed systems.

Features

• 🚀 High Performance: Atomic check-and-increment operations using DynamoDB conditional updates
• 🌍 Distributed: Works seamlessly across multiple servers/instances
• 📊 Multiple Strategies: Fixed window, sliding window, and multi-window rate limiting
• ⚡ DynamORM Integration: Built on top of Pay Theory's DynamORM for efficient DynamoDB operations
• 🔧 Flexible Configuration: Per-identifier and per-resource limits
• 🛡️ Fail-Open Option: Continue serving requests even if rate limiter fails
• 📈 Usage Statistics: Track and query usage patterns
• 🔌 HTTP Middleware: Ready-to-use HTTP middleware with customizable options

Installation

go get github.com/pay-theory/limited

Quick Start

package main

import (
    "log"
    "net/http"
    "time"

    "github.com/pay-theory/dynamorm/pkg/core"
    "github.com/pay-theory/limited"
    "github.com/pay-theory/limited/middleware"
    "go.uber.org/zap"
)

func main() {
    // Initialize DynamoDB connection
    db, err := core.NewDB(core.Config{
        Region:    "us-east-1",
        TableName: "rate-limits",
    })
    if err != nil {
        log.Fatal(err)
    }

    // Create a rate limiter with fixed window strategy
    strategy := limited.NewFixedWindowStrategy(time.Minute, 100) // 100 requests per minute
    
    limiter := limited.NewDynamoRateLimiter(
        db,
        nil,     // Use default config
        strategy,
        zap.NewExample(),
    )

    // Create HTTP middleware
    rateLimitMiddleware := middleware.Middleware(middleware.Options{
        Limiter: limiter,
        ExtractIdentifier: func(r *http.Request) string {
            // Use API key from header, fallback to IP
            if apiKey := r.Header.Get("X-API-Key"); apiKey != "" {
                return apiKey
            }
            return r.Header.Get("X-Real-IP")
        },
    })

    // Apply middleware to your handler
    http.HandleFunc("/api/endpoint", rateLimitMiddleware(handleRequest))
    
    log.Fatal(http.ListenAndServe(":8080", nil))
}

func handleRequest(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("Hello, World!"))
}

Strategies

Fixed Window

Limits requests within fixed time windows (e.g., 100 requests per minute starting at :00 seconds).

strategy := limited.NewFixedWindowStrategy(time.Minute, 100)

Sliding Window

Provides more accurate rate limiting by checking multiple sub-windows.

strategy := limited.NewSlidingWindowStrategy(
    time.Hour,        // Window size
    1000,            // Max requests per hour
    time.Minute,     // Granularity (check every minute)
)

Multi-Window

Enforces multiple limits simultaneously (e.g., 100/minute AND 1000/hour).

strategy := limited.NewMultiWindowStrategy([]limited.WindowConfig{
    {Duration: time.Minute, MaxRequests: 100},
    {Duration: time.Hour, MaxRequests: 1000},
})

Configuration

config := &limited.Config{
    DefaultRequestsPerHour:   1000,
    DefaultRequestsPerMinute: 100,
    EnableBurstCapacity:      true,
    FailOpen:                 true,  // Allow requests if rate limiter fails
    TableName:                "my-rate-limits",
    TTLHours:                 24,    // Auto-cleanup old entries
    
    // Per-identifier limits
    IdentifierLimits: map[string]limited.Limit{
        "premium-user": {
            RequestsPerHour:   10000,
            RequestsPerMinute: 1000,
        },
    },
    
    // Per-resource limits
    ResourceLimits: map[string]limited.Limit{
        "/api/expensive-operation": {
            RequestsPerHour:   100,
            RequestsPerMinute: 10,
        },
    },
}

DynamoDB Table Setup

Create a DynamoDB table with the following configuration:

TableName: rate-limits
PartitionKey: PK (String)
SortKey: SK (String)
TTL: TTL (Number) - Enable TTL on this attribute

AWS CLI Command

aws dynamodb create-table \
    --table-name rate-limits \
    --attribute-definitions \
        AttributeName=PK,AttributeType=S \
        AttributeName=SK,AttributeType=S \
    --key-schema \
        AttributeName=PK,KeyType=HASH \
        AttributeName=SK,KeyType=RANGE \
    --billing-mode PAY_PER_REQUEST

# Enable TTL
aws dynamodb update-time-to-live \
    --table-name rate-limits \
    --time-to-live-specification \
        Enabled=true,AttributeName=TTL

Advanced Usage

Custom Middleware Options

middleware.Middleware(middleware.Options{
    Limiter: limiter,
    
    // Custom identifier extraction
    ExtractIdentifier: func(r *http.Request) string {
        return r.Header.Get("X-User-ID")
    },
    
    // Custom resource extraction
    ExtractResource: func(r *http.Request) string {
        // Group endpoints by prefix
        if strings.HasPrefix(r.URL.Path, "/api/v1/") {
            return "api-v1"
        }
        return r.URL.Path
    },
    
    // Skip health checks
    SkipRequest: func(r *http.Request) bool {
        return r.URL.Path == "/health"
    },
    
    // Custom error response
    ErrorHandler: func(w http.ResponseWriter, r *http.Request, decision *limited.LimitDecision) {
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusTooManyRequests)
        json.NewEncoder(w).Encode(map[string]interface{}{
            "error": "rate_limit_exceeded",
            "retry_after": decision.RetryAfter.Seconds(),
        })
    },
    
    // Metrics collection
    OnRateLimit: func(r *http.Request, decision *limited.LimitDecision) {
        metrics.IncrCounter("rate_limit_exceeded", map[string]string{
            "resource": decision.Resource,
        })
    },
})

Direct Usage (without middleware)

// Check and increment atomically
decision, err := limiter.CheckAndIncrement(ctx, limited.RateLimitKey{
    Identifier: "user-123",
    Resource:   "api/users",
    Operation:  "GET",
})

if err != nil {
    // Handle error
}

if !decision.Allowed {
    // Request is rate limited
    fmt.Printf("Rate limited. Retry after %v\n", decision.RetryAfter)
    return
}

// Process request...

Query Usage Statistics

stats, err := limiter.GetUsage(ctx, limited.RateLimitKey{
    Identifier: "user-123",
    Resource:   "api/users",
    Operation:  "GET",
})

if err != nil {
    // Handle error
}

fmt.Printf("Current minute: %d/%d requests\n", 
    stats.CurrentMinute.Count, 
    stats.CurrentMinute.Limit)
fmt.Printf("Current hour: %d/%d requests\n", 
    stats.CurrentHour.Count, 
    stats.CurrentHour.Limit)

Testing

For testing, you can use a mock clock:

type MockClock struct {
    CurrentTime time.Time
}

func (m *MockClock) Now() time.Time {
    return m.CurrentTime
}

// In your test
mockClock := &MockClock{CurrentTime: time.Now()}
limiter.SetClock(mockClock)

// Advance time
mockClock.CurrentTime = mockClock.CurrentTime.Add(time.Minute)

Performance Considerations

1. Atomic Operations: The CheckAndIncrement method provides the best performance for high-throughput scenarios
2. Batch Operations: For bulk operations, consider implementing batch checks
3. TTL: Set appropriate TTL values to prevent table growth
4. Consistent Reads: Disable for better performance if eventual consistency is acceptable

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues, questions, or contributions, please visit github.com/pay-theory/limited