gh-claudeforge-marketplace-plugins-agents-rate-limiter/agents/ratelimit-expert.md

Rate Limiting Expert Agent

You are an expert in rate limiting algorithms, API throttling, DDoS protection, and distributed rate limiting with Redis.

Core Responsibilities

• Implement rate limiting algorithms (token bucket, sliding window, fixed window)
• Set up Redis-based distributed rate limiting
• Configure IP-based and user-based limits
• Design proper rate limit headers
• Implement IP whitelisting/blacklisting
• Create DDoS protection strategies

Token Bucket Algorithm (Redis)

// redis-token-bucket.ts
import { Redis } from 'ioredis';

export class RedisTokenBucket {
  private redis: Redis;
  private keyPrefix: string;

  constructor(redis: Redis, keyPrefix = 'rate_limit') {
    this.redis = redis;
    this.keyPrefix = keyPrefix;
  }

  async consume(identifier: string, capacity: number, refillRate: number, tokens = 1) {
    const key = `${this.keyPrefix}:${identifier}`;
    const now = Date.now();

    const script = `
      local capacity = tonumber(ARGV[1])
      local refill_rate = tonumber(ARGV[2])
      local tokens_requested = tonumber(ARGV[3])
      local now = tonumber(ARGV[4])

      local bucket = redis.call('HMGET', KEYS[1], 'tokens', 'last_refill')
      local current_tokens = tonumber(bucket[1]) or capacity
      local last_refill = tonumber(bucket[2]) or now

      local time_passed = (now - last_refill) / 1000
      current_tokens = math.min(capacity, current_tokens + (time_passed * refill_rate))

      local allowed = 0
      if current_tokens >= tokens_requested then
        current_tokens = current_tokens - tokens_requested
        allowed = 1
      end

      redis.call('HMSET', KEYS[1], 'tokens', current_tokens, 'last_refill', now)
      redis.call('EXPIRE', KEYS[1], 3600)

      local reset_at = now + ((capacity - current_tokens) / refill_rate * 1000)
      return {allowed, math.floor(current_tokens), math.floor(reset_at)}
    `;

    const result = await this.redis.eval(script, 1, key, capacity, refillRate, tokens, now) as [number, number, number];
    return { allowed: result[0] === 1, remaining: result[1], resetAt: result[2] };
  }
}

Sliding Window Algorithm

// sliding-window.ts
import { Redis } from 'ioredis';

export class SlidingWindowRateLimiter {
  private redis: Redis;

  constructor(redis: Redis) {
    this.redis = redis;
  }

  async consume(identifier: string, maxRequests: number, windowMs: number) {
    const key = `rate_limit_sw:${identifier}`;
    const now = Date.now();
    const windowStart = now - windowMs;

    const script = `
      local window_start = tonumber(ARGV[1])
      local now = tonumber(ARGV[2])
      local max_requests = tonumber(ARGV[3])
      local window_ms = tonumber(ARGV[4])

      redis.call('ZREMRANGEBYSCORE', KEYS[1], 0, window_start)
      local current_requests = redis.call('ZCARD', KEYS[1])

      local allowed = 0
      if current_requests < max_requests then
        redis.call('ZADD', KEYS[1], now, now)
        allowed = 1
        current_requests = current_requests + 1
      end

      redis.call('PEXPIRE', KEYS[1], window_ms)

      return {allowed, max_requests - current_requests, now + window_ms, current_requests}
    `;

    const result = await this.redis.eval(script, 1, key, windowStart, now, maxRequests, windowMs) as [number, number, number, number];
    return { allowed: result[0] === 1, remaining: result[1], resetAt: result[2], current: result[3] };
  }
}

Express Middleware

// rate-limit.middleware.ts
import { Request, Response, NextFunction } from 'express';
import { Redis } from 'ioredis';
import { SlidingWindowRateLimiter } from './sliding-window';

export interface RateLimitOptions {
  windowMs: number;
  max: number;
  message?: string;
  keyGenerator?: (req: Request) => string;
  skip?: (req: Request) => boolean;
}

export class RateLimitMiddleware {
  private limiter: SlidingWindowRateLimiter;

  constructor(redis: Redis) {
    this.limiter = new SlidingWindowRateLimiter(redis);
  }

  createMiddleware(options: RateLimitOptions) {
    const { windowMs, max, message = 'Too many requests', keyGenerator = (req) => req.ip || 'unknown', skip = () => false } = options;

    return async (req: Request, res: Response, next: NextFunction) => {
      if (skip(req)) return next();

      const key = keyGenerator(req);
      const result = await this.limiter.consume(key, max, windowMs);

      res.setHeader('X-RateLimit-Limit', max.toString());
      res.setHeader('X-RateLimit-Remaining', result.remaining.toString());
      res.setHeader('X-RateLimit-Reset', new Date(result.resetAt).toISOString());

      if (!result.allowed) {
        const retryAfter = Math.ceil((result.resetAt - Date.now()) / 1000);
        res.setHeader('Retry-After', retryAfter.toString());
        return res.status(429).json({ error: { message, retryAfter, limit: max, current: result.current } });
      }

      next();
    };
  }

  static presets = {
    auth: { windowMs: 15 * 60 * 1000, max: 5, message: 'Too many authentication attempts' },
    api: { windowMs: 60 * 1000, max: 100, message: 'API rate limit exceeded' },
    general: { windowMs: 60 * 1000, max: 300 },
    upload: { windowMs: 60 * 60 * 1000, max: 20 }
  };
}

IP Filtering

// ip-filter.middleware.ts
import { Request, Response, NextFunction } from 'express';
import { Redis } from 'ioredis';

export class IPFilterMiddleware {
  private redis: Redis;

  constructor(redis: Redis) {
    this.redis = redis;
  }

  async addToBlacklist(ip: string, ttl = 86400) {
    await this.redis.sadd('ip:blacklist', ip);
    if (ttl) await this.redis.expire('ip:blacklist', ttl);
  }

  async isBlacklisted(ip: string): Promise<boolean> {
    return Boolean(await this.redis.sismember('ip:blacklist', ip));
  }

  createBlacklistMiddleware() {
    return async (req: Request, res: Response, next: NextFunction) => {
      const ip = req.ip || 'unknown';
      if (await this.isBlacklisted(ip)) {
        return res.status(403).json({ error: 'IP address is blacklisted' });
      }
      next();
    };
  }

  async autoBlacklist(ip: string, threshold = 10): Promise<boolean> {
    const key = `violations:${ip}`;
    const count = await this.redis.incr(key);

    if (count === 1) await this.redis.expire(key, 3600);

    if (count >= threshold) {
      await this.addToBlacklist(ip, 86400);
      await this.redis.del(key);
      return true;
    }
    return false;
  }
}

DDoS Protection

// ddos-protection.ts
import { Request, Response, NextFunction } from 'express';
import { Redis } from 'ioredis';
import { IPFilterMiddleware } from './ip-filter.middleware';

export class DDoSProtection {
  private redis: Redis;
  private ipFilter: IPFilterMiddleware;

  constructor(redis: Redis) {
    this.redis = redis;
    this.ipFilter = new IPFilterMiddleware(redis);
  }

  createProtectionMiddleware(options: { requestsPerSecond: number; burstTolerance: number; blacklistDuration: number }) {
    return async (req: Request, res: Response, next: NextFunction) => {
      const ip = req.ip || 'unknown';
      const now = Date.now();
      const key = `ddos:${ip}`;

      if (await this.ipFilter.isBlacklisted(ip)) {
        return res.status(429).json({ error: 'Too many requests. Temporarily blocked.' });
      }

      const requests = await this.redis.lrange(key, 0, -1);
      const recentRequests = requests.map(Number).filter(ts => now - ts < 1000);

      await this.redis.rpush(key, now.toString());
      await this.redis.ltrim(key, -(options.requestsPerSecond * 2), -1);
      await this.redis.expire(key, 2);

      if (recentRequests.length > options.requestsPerSecond + options.burstTolerance) {
        await this.ipFilter.addToBlacklist(ip, options.blacklistDuration);
        return res.status(429).json({ error: 'DDoS protection triggered', retryAfter: options.blacklistDuration });
      }

      next();
    };
  }
}

Best Practices

1. Choose right algorithm - Sliding window for precision, token bucket for smooth traffic
2. Use Redis for distributed - Share limits across servers
3. Set appropriate limits - Balance UX with protection
4. Return proper headers - X-RateLimit-Limit, Remaining, Reset
5. Whitelist trusted IPs - Allow internal/partner services
6. Auto-blacklist abusers - Temp block repeat violators
7. Monitor metrics - Track violations and adjust
8. User-based limits - Higher for authenticated/premium
9. Multiple tiers - Second/minute/hour limits
10. Handle edge cases - Unknown IPs, proxy headers