Rate Limit Gateway

A high-performance, distributed rate limiting gateway built with Node.js and TypeScript. Features Redis-backed token bucket algorithm, REST/gRPC APIs, and comprehensive monitoring.

🚀 Features

• Distributed Rate Limiting: Redis-backed with in-memory fallback
• Multiple Algorithms: Token Bucket and Leaky Bucket implementations
• Dual Protocol Support: REST API and gRPC endpoints
• SDK Support: Node.js and Python SDKs
• Production Ready: Docker support, Prometheus metrics, health checks
• Middleware Integration: Easy Express.js integration
• Observability: Prometheus metrics and structured logging

📦 Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Node.js SDK   │    │   Python SDK    │    │   Your App      │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │   Rate Limit Gateway      │
                    │  ┌─────────────────────┐  │
                    │  │   REST API (8080)   │  │
                    │  │   gRPC API (9090)   │  │
                    │  │   Metrics (/metrics)│  │
                    │  └─────────────────────┘  │
                    └─────────────┬─────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │        Redis             │
                    │   (Distributed Store)   │
                    └─────────────────────────┘

🛠 Quick Start

Using Docker Compose (Recommended)

# Clone the repository
git clone https://github.com/your-username/rate-limit-gateway.git
cd rate-limit-gateway

# Start the gateway and Redis
docker-compose up -d

# Check health
curl http://localhost:8080/health

# View metrics
curl http://localhost:8080/metrics/json

Manual Setup

# Install dependencies
npm install

# Start Redis (if not using Docker)
redis-server

# Start the gateway
npm run dev

📚 API Usage

REST API

Check Rate Limit

curl -X POST http://localhost:8080/v1/check \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your-api-key",
    "identifier": "user123",
    "path": "/api/users",
    "method": "GET"
  }'

Response:

{
  "allowed": true,
  "remaining": 99,
  "limit": 100,
  "reset": 1670000000
}

Health Check

curl http://localhost:8080/health

Metrics

# Prometheus format
curl http://localhost:8080/metrics

# JSON format
curl http://localhost:8080/metrics/json

gRPC API

The gRPC service is available on port 9090 with the same Check RPC method.

🔧 Node.js SDK

Installation

npm install @himanshu/rate-limit-gateway

Usage

const { RateLimitClient, createRateLimitMiddleware } = require('@himanshu/rate-limit-gateway');

// Initialize client
const client = new RateLimitClient({
  baseUrl: 'http://localhost:8080',
  grpcUrl: 'localhost:9090',
  apiKey: 'your-api-key'
});

// Check rate limit
const result = await client.checkLimit({
  identifier: 'user123',
  path: '/api/users',
  method: 'GET'
});

console.log(result.allowed); // true/false
console.log(result.remaining); // remaining tokens

Express Middleware

const express = require('express');
const { createRateLimitMiddleware } = require('@himanshu/rate-limit-gateway');

const app = express();

// Apply rate limiting
app.use(createRateLimitMiddleware(client));

app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

🐍 Python SDK

Installation

pip install ratelimit-gateway

Usage

from ratelimit_gateway import RateLimitClient, create_rate_limit_middleware

# Initialize client
client = RateLimitClient(
    base_url='http://localhost:8080',
    api_key='your-api-key',
    grpc_url='localhost:9090'
)

# Check rate limit
result = client.check_limit(
    identifier='user123',
    path='/api/users',
    method='GET'
)

print(result['allowed'])  # True/False
print(result['remaining'])  # remaining tokens

Flask Middleware

from flask import Flask
from ratelimit_gateway import create_rate_limit_middleware

app = Flask(__name__)

# Apply rate limiting
middleware = create_rate_limit_middleware(client)
app.before_request(middleware['flask'])

@app.route('/api/users')
def get_users():
    return {'users': []}

⚙️ Configuration

Gateway Configuration

{
  "port": 8080,
  "redis": {
    "url": "redis://localhost:6379"
  },
  "limits": {
    "default": {
      "capacity": 100,
      "refillRatePerSecond": 1
    },
    "perRoute": {
      "GET:/api/users": {
        "capacity": 50,
        "refillRatePerSecond": 2
      }
    }
  },
  "auth": {
    "type": "apiKey"
  },
  "grpc": {
    "port": 9090
  },
  "prometheus": {
    "enabled": true
  }
}

Environment Variables

• PORT: Gateway HTTP port (default: 8080)
• GRPC_PORT: Gateway gRPC port (default: 9090)
• REDIS_URL: Redis connection URL
• NODE_ENV: Environment (development/production)

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run integration tests
npm run test:integration

# Run Python tests
cd sdk-python
python -m pytest tests/ -v

📊 Monitoring

Prometheus Metrics

The gateway exposes Prometheus metrics at /metrics:

• requests_total: Total number of requests
• requests_blocked_total: Number of blocked requests
• request_latency_seconds: Request latency histogram

Health Checks

• HTTP: GET /health
• Docker: Built-in health check
• Kubernetes: Liveness and readiness probes

🚀 Deployment

Docker

# Build image
docker build -t rate-limit-gateway .

# Run with Redis
docker run -d --name redis redis:7-alpine
docker run -d --name gateway --link redis -p 8080:8080 rate-limit-gateway

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: rate-limit-gateway
spec:
  replicas: 3
  selector:
    matchLabels:
      app: rate-limit-gateway
  template:
    metadata:
      labels:
        app: rate-limit-gateway
    spec:
      containers:
      - name: gateway
        image: himanshu/rate-limit-gateway:latest
        ports:
        - containerPort: 8080
        env:
        - name: REDIS_URL
          value: "redis://redis-service:6379"

🔒 Security

• API key authentication
• JWT support (optional)
• Rate limit headers (X-RateLimit-*)
• Retry-After headers for blocked requests
• Input validation and sanitization

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• GitHub Issues: Create an issue
• Documentation: Wiki
• Examples: examples/ directory

🗺 Roadmap

• [ ] WebSocket support
• [ ] GraphQL rate limiting
• [ ] Advanced algorithms (Sliding Window, etc.)
• [ ] Admin dashboard
• [ ] Multi-region support
• [ ] Rate limit analytics

Made with ❤️ by Himanshu