Designing a Distributed Rate Limiter

Check several fixed-window limits in one atomic call; nothing is counted if any limit rejects.

-- KEYS[i] = counter keys (same hash tag); ARGV[i] = limits; ARGV[#KEYS+1] = window sec
local n = #KEYS
local window = tonumber(ARGV[n + 1])
for i = 1, n do
  local c = tonumber(redis.call('GET', KEYS[i]) or '0')
  if c >= tonumber(ARGV[i]) then
    return {0, i}                         -- rejected by limit i
  end
end
for i = 1, n do
  if redis.call('INCR', KEYS[i]) == 1 then
    redis.call('EXPIRE', KEYS[i], window)
  end
end
return {1, 0}

@Component
public class RateLimitFilter extends OncePerRequestFilter {
    private final RedisRateLimiter redisLimiter;          // wraps the Lua script
    private final LocalRateLimiter fallback;              // e.g. Bucket4j in memory
    private final MeterRegistry metrics;

    @Override
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res, FilterChain chain)
            throws IOException, ServletException {
        String user = currentUserId(req);
        Plan plan = plans.forUser(user);                  // cached locally
        Decision d;
        try {
            d = redisLimiter.check(user, req.getRequestURI(), plan);   // ~0.5 ms, 5 ms timeout
        } catch (RedisConnectionFailureException | QueryTimeoutException e) {
            metrics.counter("ratelimit.redis_error").increment();
            d = fallback.check(user, plan);               // fail open, but still bounded locally
        }
        if (!d.allowed()) {
            res.setStatus(429);
            res.setHeader("Retry-After", String.valueOf(d.retryAfterSeconds()));
            return;
        }
        res.setHeader("X-RateLimit-Remaining", String.valueOf(d.remaining()));
        chain.doFilter(req, res);
    }
}