Capstone: Build a Feature End-to-End with AI

I need to add rate limiting to our Express.js/TypeScript
API. We use Redis already for caching.

Compare these rate limiting approaches for our situation:
1. Fixed window counter
2. Sliding window log
3. Sliding window counter
4. Token bucket

Our constraints:
- ~10,000 active users
- Need per-user, per-endpoint limits
- Running 3 API server instances behind a load balancer
- Redis available (already in our stack)
- Must handle 1,000 req/sec peak

For each approach, analyze: accuracy, Redis memory usage,
implementation complexity, and behavior at window boundaries.

Implement a rate limiting middleware for Express.js
with TypeScript.

Algorithm: Sliding window counter using Redis
Storage: Our existing Redis instance (ioredis client)

Our middleware pattern:
[paste an existing middleware as example]

Requirements:
- Accepts config: { windowMs: number, maxRequests: number }
- Key format: ratelimit:{userId}:{endpoint}:{windowId}
- Returns 429 with Retry-After header when limit exceeded
- Adds X-RateLimit-* headers to all responses
- Handles Redis connection failures gracefully (fail open)
- TypeScript with strict types

Generate:
1. The RateLimitConfig interface
2. The middleware factory function
3. The Redis operations (increment, check, cleanup)

interface RateLimitConfig {
  windowMs: number;
  maxRequests: number;
  keyPrefix?: string;
  failOpen?: boolean;
}

const createRateLimiter = (config: RateLimitConfig) => {
  return async (req: Request, res: Response, next: NextFunction) => {
    const userId = req.user?.id ?? req.ip;
    const endpoint = req.route?.path ?? req.path;
    const windowId = Math.floor(Date.now() / config.windowMs);
    const prevWindowId = windowId - 1;

    const currentKey = `ratelimit:${userId}:${endpoint}:${windowId}`;
    const prevKey = `ratelimit:${userId}:${endpoint}:${prevWindowId}`;

    try {
      const [currentCount, prevCount] = await Promise.all([
        redis.incr(currentKey),
        redis.get(prevKey),
      ]);

      // Set expiry on current window key
      if (currentCount === 1) {
        await redis.expire(currentKey, Math.ceil(config.windowMs / 1000) * 2);
      }

      // Sliding window calculation
      const elapsed = (Date.now() % config.windowMs) / config.windowMs;
      const weight = (Number(prevCount) || 0) * (1 - elapsed) + currentCount;

      const remaining = Math.max(0, config.maxRequests - Math.ceil(weight));
      const resetTime = (windowId + 1) * config.windowMs;

      res.set({
        'X-RateLimit-Limit': String(config.maxRequests),
        'X-RateLimit-Remaining': String(remaining),
        'X-RateLimit-Reset': String(Math.ceil(resetTime / 1000)),
      });

      if (remaining <= 0) {
        const retryAfter = Math.ceil((resetTime - Date.now()) / 1000);
        res.set('Retry-After', String(retryAfter));
        return res.status(429).json({
          error: 'Too many requests',
          retryAfter,
        });
      }

      next();
    } catch (error) {
      if (config.failOpen !== false) {
        next(); // Fail open: allow request if Redis is down
      } else {
        res.status(503).json({ error: 'Service temporarily unavailable' });
      }
    }
  };
};

I'm seeing a race condition in my rate limiter. When
10 concurrent requests arrive, the counter sometimes
shows 8 or 9 instead of 10.

Here's the code:
[paste the middleware]

The issue: redis.incr() and redis.get() are separate
commands. Between the INCR and GET, another request
could modify the counter.

How do I fix this race condition?

local current = redis.call('INCR', KEYS[1])
if current == 1 then
  redis.call('EXPIRE', KEYS[1], ARGV[1])
end
local prev = redis.call('GET', KEYS[2]) or 0
return {current, prev}

Write comprehensive tests for this rate limiting middleware
using Jest and supertest.

[paste the final middleware code]

Test categories needed:
1. Basic rate limiting (requests within limit pass, over limit returns 429)
2. Sliding window behavior (requests in previous window affect current)
3. Header correctness (X-RateLimit-* headers have correct values)
4. Redis failure handling (fail open behavior)
5. Per-user isolation (user A's requests don't affect user B)
6. Per-endpoint isolation (calls to /api/users don't count against /api/posts)
7. Window reset behavior (limit resets after window passes)
8. Concurrent request handling

Use jest.useFakeTimers() for time-dependent tests.
Mock Redis for unit tests.

Review this rate limiting middleware for production readiness.

Focus on:
1. Security: Can users bypass the rate limit?
2. Performance: Any bottlenecks under load?
3. Reliability: What happens when things go wrong?
4. Correctness: Is the sliding window math right?

[paste the complete middleware code and tests]

Generate documentation for our rate limiting middleware.
Audience: developers on our team who need to add rate
limiting to their endpoints.

Include:
1. Quick start (how to add rate limiting to a route)
2. Configuration options with defaults
3. How the sliding window algorithm works (brief)
4. Response headers explained
5. Error responses
6. Common configurations (strict for auth, relaxed for reads)
7. Troubleshooting guide

[paste the final middleware code]