How do you build a sliding-window rate limiter with Redis + Lua?

// A tiny in-process stand-in for a Redis sorted set, used to show why the sliding-window
// limiter must run as ONE atomic Lua script. Limit 5 per 1000 ms; fake clock in ms.
class MiniRedis {
  constructor() { this.z = new Map(); } // key -> Map(member -> score)
  set(key) { if (!this.z.has(key)) this.z.set(key, new Map()); return this.z.get(key); }
  zremrangebyscore(key, max) { const s = this.set(key); for (const [m, sc] of s) if (sc <= max) s.delete(m); }
  zcard(key) { return this.set(key).size; }
  zadd(key, score, member) { this.set(key).set(member, score); }
  oldest(key) { let best = Infinity; for (const sc of this.set(key).values()) best = Math.min(best, sc); return best; }
}

const WINDOW = 1000, LIMIT = 5;

// The body of the Lua script. Redis runs it without interleaving any other command.
function script(r, key, now, member) {
  r.zremrangebyscore(key, now - WINDOW);
  const count = r.zcard(key);
  if (count < LIMIT) { r.zadd(key, now, member); return [1, LIMIT - count - 1, 0]; }
  return [0, 0, r.oldest(key) + WINDOW - now];
}

console.log("== 1. the script, one client (same calls as the redis-cli run)");
let r = new MiniRedis();
let n = 0;
for (const now of [1000, 1100, 1200, 1300, 1400, 1500, 1600, 2001]) {
  n++;
  console.log("  now=" + now + "  [allowed remaining retry_ms] = " + script(r, "rl:{user42}", now, now + "-req" + n).join(" "));
}

console.log("== 2. four gateways, three rounds of simultaneous requests");
function race(atomic) {
  const r = new MiniRedis();
  let admitted = 0, id = 0;
  for (let round = 0; round < 3; round++) {
    const now = round * 10;
    if (atomic) {
      for (let g = 0; g < 4; g++) admitted += script(r, "k", now, "req" + id++)[0];
    } else {
      // check-then-act from the client: every gateway reads before any of them writes
      const seen = [];
      for (let g = 0; g < 4; g++) { r.zremrangebyscore("k", now - WINDOW); seen.push(r.zcard("k")); }
      for (let g = 0; g < 4; g++) if (seen[g] < LIMIT) { r.zadd("k", now, "req" + id++); admitted++; }
    }
  }
  return admitted;
}
console.log("  ZCARD then ZADD as separate commands: admitted " + race(false) + " of 12 (limit 5)");
console.log("  one Lua script per request:           admitted " + race(true) + " of 12 (limit 5)");

console.log("== 3. member = timestamp vs a unique member, 4 requests in each of 3 milliseconds");
for (const unique of [false, true]) {
  const r = new MiniRedis();
  let admitted = 0, id = 0;
  for (let ms = 0; ms < 3; ms++) {
    for (let g = 0; g < 4; g++) admitted += script(r, "k", ms, unique ? ms + "-req" + id++ : String(ms))[0];
  }
  console.log("  member " + (unique ? "now-requestId" : "now          ") + "  admitted " + admitted + " of 12, ZCARD " + r.zcard("k"));
}

console.log("== 4. a client sending every 100 ms for 3 s: should denied requests be recorded?");
for (const recordDenied of [false, true]) {
  const r = new MiniRedis();
  let admitted = 0;
  const perSecond = [0, 0, 0];
  for (let i = 0; i < 30; i++) {
    const now = i * 100;
    let ok;
    if (recordDenied) {
      r.zremrangebyscore("k", now - WINDOW);
      ok = r.zcard("k") < LIMIT ? 1 : 0;
      r.zadd("k", now, "req" + i); // logged even when denied
    } else ok = script(r, "k", now, "req" + i)[0];
    admitted += ok;
    perSecond[Math.floor(now / 1000)] += ok;
  }
  console.log("  " + (recordDenied ? "denied requests recorded" : "only allowed recorded   ") + "  admitted " + admitted + " of 30, per second " + perSecond.join(" "));
}