hono-redis-kappe

A flexible and extensible rate limiting middleware for Hono, powered by Redis. This package helps you protect your Hono applications from abuse and ensures fair resource usage by limiting the number of requests a client can make within a specified time window.

Features

• Redis-backed: Leverages Redis for efficient and distributed rate limiting across multiple instances.
• Highly Customizable: Provides interfaces and classes to customize key generation, error responses, and header management.
• Immutable Configuration: Uses immutable patterns for robust and predictable configuration management.

Installation

1npm install hono-redis-kappe ioredis

Usage

Basic Usage

The simplest way to use the rate limiter is with its default settings, which limit requests based on the client's IP address.

1import { Hono } from "hono";
2import { Redis } from "ioredis";
3import { RateLimiterFactory } from "hono-redis-kappe";
4
5const app = new Hono();
6const redis = new Redis();
7
8app.use(
9  "*",
10  RateLimiterFactory.create({
11    redis,
12    requestLimit: 100,
13    timeWindowSeconds: 60,
14  }),
15);
16
17app.get("/", (c) => {
18  return c.text("Hello Hono!");
19});
20
21export default app;

Customizing Key Generation

You can define how the rate limit key is generated by implementing the IKeyGenerator interface or by using the FunctionBasedKeyGenerator.

IP-Based (Default)

The default IpBasedKeyGenerator attempts to get the client's IP from x-forwarded-for, cf.ip (Cloudflare), or x-real-ip headers.

1import { RateLimiterFactory, IpBasedKeyGenerator } from "hono-redis-kappe";
2
3const rateLimiter = RateLimiterFactory.create({
4  redis: redis,
5  keyGenerator: new IpBasedKeyGenerator(),
6});

Custom Function-Based Key Generation

You can provide a function to generate the key based on your specific needs, for example, by user ID from a session or JWT.

1import { RateLimiterFactory, FunctionBasedKeyGenerator } from "hono-redis-kappe";
2
3const rateLimiter = RateLimiterFactory.create({
4  redis: redis,
5  keyGenerator: new FunctionBasedKeyGenerator((c) => {
6    const userId = c.get("jwtPayload")?.sub;
7    return userId || c.req.header("x-forwarded-for") || "anonymous";
8  }),
9});

Handling Rate Limit Errors

By default, an HTTPException with status 429 (Too Many Requests) is thrown. You can customize this behavior.

1import { RateLimiterFactory, DefaultErrorResponseHandler } from "hono-redis-kappe";
2
3const rateLimiter = RateLimiterFactory.create({
4  redis: redis,
5  errorResponseHandler: new DefaultErrorResponseHandler(),
6});

JSON Error Response

You can return a JSON response with or without detailed information.

1import { RateLimiterFactory, JsonErrorResponseHandler } from "hono-redis-kappe";
2
3const rateLimiterJsonDetailed = RateLimiterFactory.create({
4  redis: redis,
5  errorResponseHandler: new JsonErrorResponseHandler(true), // with details (default)
6});
7
8const rateLimiterJsonSimple = RateLimiterFactory.create({
9  redis: redis,
10  errorResponseHandler: new JsonErrorResponseHandler(false), // without details
11});

Reusable Factory for Multiple Configurations

If you have multiple endpoints requiring different rate limit configurations, you can create a reusable factory.

1import { Hono } from "hono";
2import { Redis } from "ioredis";
3import { RateLimiterFactory } from "hono-redis-kappe";
4
5const app = new Hono().basePath("/api");
6const redis = new Redis();
7
8const rateLimiter = RateLimiterFactory.createReusableFactory({
9  redis: redis,
10  keyPrefix: "rate_limit",
11});
12
13app.get(
14  "/public",
15  rateLimiter({
16    requestLimit: 150,
17    timeWindowSeconds: 60,
18  }),
19  (c) => c.text("This is a public endpoint."),
20);
21
22app.get(
23  "/private",
24  rateLimiter({
25    requestLimit: 50,
26    timeWindowSeconds: 60,
27    // tip: you could also override the keyGenerator here for user-specific limits
28  }),
29  (c) => c.text("This is a private endpoint."),
30);
31
32app.get(
33  "/constrained",
34  rateLimiter({
35    requestLimit: 1,
36    timeWindowSeconds: 300,
37  }),
38  (c) => c.text("This is a constrained endpoint."),
39);
40
41export default app;

License

This project is licensed under the MIT License.