cutz-redis-ratelimit (1.0.1)

cutz-redis-ratelimit is a simple and efficient rate limiting library using Upstash Redis. It provides built-in methods for handling rate limiting, calculating retry times, and creating rate limit responses.

Installation

Install the package using npm:

1npm i cutz-redis-ratelimit

Usage

Importing the Library

1import { Ratelimit } from "cutz-redis-ratelimit";

Creating a Ratelimit Instance

Create an instance of the Ratelimit class by providing the necessary configuration options:

1const ratelimit = new Ratelimit({
2  url: process.env.UPSTASH_REDIS_URL ?? "",
3  token: process.env.UPSTASH_REDIS_TOKEN ?? "",
4  time: "10 s",
5  maxRequests: 1,
6  logging: true,                        // optional
7  whitelist: ['127.0.0.1'],             // optional
8  blacklist: ['203.0.113.1'],           // optional
9  blacklistConfig: {                    // optional
10    blockDuration: 7200 * 1000,
11    message: "Your IP has been blacklisted.",
12  },
13});

Using the Ratelimit Instance

Use the ratelimit instance to limit requests based on the client's IP address:

1import { NextResponse } from "next/server";
2import { Ratelimit } from "cutz-redis-ratelimit";
3
4const ratelimit = new Ratelimit({
5  url: process.env.UPSTASH_REDIS_URL,
6  token: process.env.UPSTASH_REDIS_TOKEN,
7  windowSize: "10 s",
8  maxRequests: 1,
9});
10
11export async function GET(req: Request) {
12  const ip = req.headers.get("x-forwarded-for") ?? "";
13  const { success, reset } = await ratelimit.limit(ip);
14
15  if (!success) {
16    const retryAfter = ratelimit.getRetryAfter(reset);
17    return ratelimit.createRateLimitResponse(retryAfter);
18  }
19
20  try {
21    return NextResponse.json(
22      { message: "Request successful" },
23      { status: 200 }
24    );
25  } catch (error) {
26    return NextResponse.json(
27      { error: "Failed to do something...." },
28      { status: 500 }
29    );
30  }
31}

API

Ratelimit Class

Constructor

1constructor(options: RatelimitOptions)

• options: An object containing the following properties:
  • url: The Upstash Redis URL.
  • token: The Upstash Redis token.
  • time: The time duration for the ratelimit (e.g., "10 s").
  • maxRequests: The maximum number of requests allowed within the window.
  • logging: (Optional) Enable logging for debugging purposes.
  • whitelist: (Optional) An array of IP addresses to whitelist.
  • blacklist: (Optional) An array of IP addresses to blacklist.
  • blacklistConfig: (Optional) Configuration for blacklisted IPs, including block duration and message.

Methods

1limit(ip: string): Promise<{ success: boolean; reset: number; }>

Limits the number of requests based on the client's IP address.

• ip: The client's IP address.
• Returns a promise that resolves to an object containing:
  • success: A boolean indicating whether the request is allowed.
  • reset: The timestamp when the rate limit will reset.

1getRetryAfter(reset: number): number

Calculates the retry-after time in seconds.

• reset: The timestamp when the rate limit will reset.
• Returns the retry-after time in seconds.

1createRateLimitResponse(retryAfter: number): Response

Creates a rate limit response with the appropriate headers.

• retryAfter: The retry-after time in seconds.
• Returns a Response object with a 429 status code and the retry-after header.

1createBlacklistResponse(): Response

Creates a blacklist response with the appropriate message.

• Returns a Response object with a 403 status code and the blacklist message.

1updateConfig({ time, maxRequests }: { time: Duration; maxRequests: number }): void

Updates the rate limit configuration.

• time: The new time duration for the rate limit.
• maxRequests: The new maximum number of requests allowed within the window.

License

This project is licensed under the ISC License.