Rate Limiter

pnpm dlx blockend-cli add rate-limiter

// --- Core Interfaces ---
export interface RateLimitRecord {
  hits: number;
  resetTime: number; // Unix timestamp in ms
}

export interface RateLimitStore {
  increment(key: string, windowMs: number): Promise<RateLimitRecord> | RateLimitRecord;
}

export interface RateLimitConfig {
  windowMs: number;
  max: number;
  statusCode: number;
  message: string | Record<string, unknown>;
  standardHeaders: boolean;
  legacyHeaders: boolean; // <-- Added flag for backwards compatibility
}
export interface RateLimitResult {
  isBlocked: boolean;
  statusCode: number;
  message: string | Record<string, unknown>;
  headers: Record<string, string>;
}

// --- The Core Engine ---
export async function evaluateRateLimit(
  key: string,
  store: RateLimitStore,
  config: RateLimitConfig
): Promise<RateLimitResult> {
  const { hits, resetTime } = await store.increment(key, config.windowMs);
  const remaining = Math.max(0, config.max - hits);
  const now = Date.now();

  const retryAfterSeconds = Math.ceil(Math.max(0, resetTime - now) / 1000);
  const headers: Record<string, string> = {};
  const isBlocked = hits > config.max;

  // 1. Modern Standard Headers (RFC 9421 Draft Compliant)
  if (config.standardHeaders) {
    headers["RateLimit-Limit"] = `${config.max}, window=${Math.ceil(config.windowMs / 1000)}`;
    headers["RateLimit-Remaining"] = String(remaining);
    headers["RateLimit-Reset"] = String(retryAfterSeconds); // Remaining seconds
  }

  // 2. Legacy Headers (De facto Industry Standard - GitHub, Twitter, etc.)
  if (config.legacyHeaders) {
    headers["X-RateLimit-Limit"] = String(config.max);
    headers["X-RateLimit-Remaining"] = String(remaining);
    headers["X-RateLimit-Reset"] = String(Math.ceil(resetTime / 1000)); // Absolute Unix Epoch timestamp in seconds
  }

  if (isBlocked) {
    headers["Retry-After"] = String(retryAfterSeconds);
    return {
      isBlocked: true,
      statusCode: config.statusCode,
      message: config.message,
      headers
    };
  }

  return {
    isBlocked: false,
    statusCode: 200,
    message: "",
    headers
  };
}

export function getClientIp(
  headers: Record<string, string | string[] | undefined>,
  remoteAddress?: string
): string {
  // 1. Check standard proxy headers (if you trust your upstream proxy environment)
  const xForwardedFor = headers["x-forwarded-for"];
  if (xForwardedFor) {
    const ips =
      typeof xForwardedFor === "string" ? xForwardedFor.split(",") : xForwardedFor[0]!.split(",");

    return ips[0]!.trim(); // The first IP is the actual client
  }
  const xRealIp = headers["x-real-ip"];
  if (typeof xRealIp === "string") return xRealIp;
  // 2. Fall back to raw socket address
  return remoteAddress || "unknown-ip";
}

import type { Request, Response, NextFunction } from "express";
import { evaluateRateLimit } from "../core/core";
import type { RateLimitStore, RateLimitConfig } from "../core/core";
import { getClientIp } from "../utils/ip";

export interface ExpressOptions extends Partial<RateLimitConfig> {
  store: RateLimitStore;
  keyGenerator?: (req: Request) => string;
}

export const expressRateLimit = (options: ExpressOptions) => {
  const config: RateLimitConfig = {
    windowMs: 60 * 1000,
    max: 100,
    statusCode: 429,
    message: { error: "Too many requests, please try again later." },
    standardHeaders: true,
    legacyHeaders: true,
    ...options
  };

  const keyGen =
    options.keyGenerator || ((req: Request) => getClientIp(req.headers, req.socket.remoteAddress));

  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
    try {
      const key = keyGen(req);
      const result = await evaluateRateLimit(key, options.store, config);

      // Set computed rate limit headers dynamically
      for (const [name, value] of Object.entries(result.headers)) {
        res.setHeader(name, value);
      }

      if (result.isBlocked) {
        res.status(result.statusCode).send(result.message);
        return;
      }

      next();
    } catch (error) {
      // oxlint-disable-next-line no-console
      console.error("Rate limiter failure (Fail-Open):", error);
      next(); // Fail-open pattern intact
    }
  };
};

import type { FastifyRequest, FastifyReply } from "fastify";
import { evaluateRateLimit } from "../core/core";
import type { RateLimitStore, RateLimitConfig } from "../core/core";
import { getClientIp } from "../utils/ip";

export interface FastifyOptions extends Partial<RateLimitConfig> {
  store: RateLimitStore;
  keyGenerator?: (req: FastifyRequest) => string;
}

export const fastifyRateLimit = (options: FastifyOptions) => {
  const config: RateLimitConfig = {
    windowMs: 60 * 1000,
    max: 100,
    statusCode: 429,
    message: { error: "Too many requests, please try again later." },
    standardHeaders: true,
    legacyHeaders: true,
    ...options
  };

  const keyGen =
    options.keyGenerator ||
    ((req: FastifyRequest) => getClientIp(req.headers, req.socket.remoteAddress));

  return async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
    try {
      const key = keyGen(request);
      const result = await evaluateRateLimit(key, options.store, config);

      reply.headers(result.headers);

      if (result.isBlocked) {
        reply.code(result.statusCode).send(result.message);
        return; // Halts request lifecycle execution in Fastify hooks
      }
    } catch (error) {
      request.log.error(error, "Rate limiter failure (Fail-Open)");
      // Async hook implicit return continues execution automatically (Fail-Open)
    }
  };
};

import { evaluateRateLimit } from "../core/core";
import type { RateLimitStore, RateLimitConfig } from "../core/core";
import { getClientIp } from "../utils/ip";
import type { ContentfulStatusCode } from "hono/utils/http-status";
import type { Context, MiddlewareHandler } from "hono";

export interface HonoOptions extends Partial<RateLimitConfig> {
  store: RateLimitStore;
  keyGenerator?: (c: Context) => string;
}

export const honoRateLimit = (options: HonoOptions): MiddlewareHandler => {
  const config: RateLimitConfig = {
    windowMs: 60 * 1000,
    max: 100,
    statusCode: 429,
    message: { error: "Too many requests, please try again later." },
    standardHeaders: true,
    legacyHeaders: true,
    ...options
  };

  const keyGen =
    options.keyGenerator ||
    ((c: Context) => getClientIp(Object.fromEntries(c.req.raw.headers.entries()), undefined));

  return async (c, next) => {
    try {
      const key = keyGen(c);
      const result = await evaluateRateLimit(key, options.store, config);

      // Set computed rate limit headers dynamically
      for (const [name, value] of Object.entries(result.headers)) {
        c.header(name, value);
      }

      if (result.isBlocked) {
        return c.json(result.message, result.statusCode as ContentfulStatusCode);
      }

      await next();
    } catch (error) {
      //oxlint-disable-next-line no-console
      console.error("Rate limiter failure (Fail-Open):", error);
      await next(); // Fail-open pattern intact
    }
  };
};

import type { RateLimitRecord, RateLimitStore } from "../core/core";

interface QueueEntry {
  key: string;
  resetTime: number;
}

export class MemoryStore implements RateLimitStore {
  private readonly store = new Map<string, RateLimitRecord>();
  // High-Performance Addition: A chronological queue tracking when keys expire
  private readonly expirationQueue: QueueEntry[] = [];
  private queueIndex = 0;

  public constructor() {
    // Periodically run a bounded incremental purge instead of a full loop
    setInterval(() => this.purge(), 60 * 1000).unref();
  }

  public increment(key: string, windowMs: number): RateLimitRecord {
    const now = Date.now();
    const existing = this.store.get(key);

    // 80/20 Optimization: Inline eviction if the key is already expired
    if (existing && now > existing.resetTime) {
      this.store.delete(key);
    }

    let record: RateLimitRecord;

    if (existing && now <= existing.resetTime) {
      record = {
        hits: existing.hits + 1,
        resetTime: existing.resetTime
      };
    } else {
      record = {
        hits: 1,
        resetTime: now + windowMs
      };
      // Track this key's expiration chronologically
      this.expirationQueue.push({ key, resetTime: record.resetTime });
    }

    this.store.set(key, record);

    return { ...record };
  }

  private purge(): void {
    const now = Date.now();

    // Chronological Sweep: Since items are appended in order of expiration time,
    // we only look at the oldest items at the front of our queue.
    // The moment we hit an item that hasn't expired yet, we can STOP instantly.
    while (this.queueIndex < this.expirationQueue.length) {
      const entry = this.expirationQueue[this.queueIndex]!;

      if (entry.resetTime > now) {
        break; // Stop immediately. Everything after this is still valid.
      }

      // Evict from map if the current record matches this expiration mark
      const currentRecord = this.store.get(entry.key);
      if (currentRecord && currentRecord.resetTime <= now) {
        this.store.delete(entry.key);
      }

      this.queueIndex++;
    }

    // Memory clean up for the queue array itself once it grows large
    if (this.queueIndex > 10000) {
      this.expirationQueue.splice(0, this.queueIndex);
      this.queueIndex = 0;
    }
  }
}

import type { Redis } from "ioredis";
import type { RateLimitStore, RateLimitRecord } from "../core/core";

export interface RedisWithRateLimit extends Redis {
  performRateLimitIncrement(key: string, windowMs: number): Promise<[number, number]>;
}
export class RedisStore implements RateLimitStore {
  constructor(
    private redisClient: RedisWithRateLimit,
    private keyPrefix = "rl:"
  ) {
    // Define the atomic rate limit script inside ioredis once on startup
    this.redisClient.defineCommand("performRateLimitIncrement", {
      numberOfKeys: 1,
      lua: `
        local key = KEYS[1]
        local windowMs = tonumber(ARGV[1])

        -- 1. Increment the hit counter
        local hits = redis.call('INCR', key)

        -- 2. If it's a brand new key, immediately anchor its exact millisecond TTL
        if hits == 1 then
            redis.call('PEXPIRE', key, windowMs)
        end

        -- 3. Fetch the exact remaining millisecond TTL
        local pttl = redis.call('PTTL', key)

        return {hits, pttl}
      `
    });
  }

  async increment(key: string, windowMs: number): Promise<RateLimitRecord> {
    const fullKey = `${this.keyPrefix}${key}`;
    const now = Date.now();

    // Execute the atomic script in exactly 1 network round-trip
    // We cast to 'any' because we added a custom dynamic command name above
    const [hits, pttl] = (await this.redisClient.performRateLimitIncrement(fullKey, windowMs)) as [
      number,
      number
    ];

    // Handle defensive fallback if PTTL returns a negative error code
    const actualRemainingMs = pttl > 0 ? pttl : windowMs;

    return {
      hits,
      resetTime: now + actualRemainingMs
    };
  }
}