🔥@hono-rate-limiter/cloudflare🔥

This package includes WorkersKV and Durable Object store for the hono-rate-limiter middleware and cloudflareRateLimiter func for Workers Rate Limiting API.

[!NOTE]
The keyGenerator function and rateLimitBinding bindings needs to be defined for cloudflareRateLimiter to work properly in your environment. Please ensure that you define the keyGenerator function according to the documentation before using the library.

Installation

1# Using npm/yarn/pnpm/bun
2npm add @hono-rate-limiter/cloudflare

Usage

Examples

Using cloudflareRateLimiter

1# wrangler.toml
2# The rate limiting API is in open beta.
3[[unsafe.bindings]]
4name = "MY_RATE_LIMITER"
5type = "ratelimit"
6# An identifier you define, that is unique to your Cloudflare account.
7# Must be an integer.
8namespace_id = "1001"
9
10# Limit: the number of tokens allowed within a given period in a single
11# Cloudflare location
12# Period: the duration of the period, in seconds. Must be either 10 or 60
13simple = { limit = 100, period = 60 }

For more info on setting up your Workers Rate Limiting API you can check out Rate Limiting Guide on cloudflare.

1import { cloudflareRateLimiter } from "@hono-rate-limiter/cloudflare";
2
3type AppType = {
4  Variables: {
5    rateLimit: boolean;
6  };
7  Bindings: {
8    RATE_LIMITER: RateLimit;
9  };
10};
11
12// Apply the rate limiting middleware to all requests.
13const app = new Hono<AppType>().use(
14  cloudflareRateLimiter<AppType>({
15    rateLimitBinding: (c) => c.env.RATE_LIMITER,
16    keyGenerator: (c) => c.req.header("cf-connecting-ip") ?? "", // Method to generate custom identifiers for clients.
17  })
18);

Using WorkersKVStore

1# wrangler.toml
2[[kv_namespaces]]
3binding = "CACHE"
4id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

For more info on setting up your WorkersKV you can check out Get Started Guide on cloudflare.

1// index.ts
2import { WorkersKVStore } from "@hono-rate-limiter/cloudflare";
3import { rateLimiter } from "hono-rate-limiter";
4import { Context, Next } from "hono";
5import { KVNamespace } from "cloudflare:worker";
6
7// Add this in Hono app
8type Bindings = {
9  CACHE: KVNamespace;
10  // ... other binding types
11};
12
13const app = new Hono<{ Bindings: Bindings }>();
14
15// Apply the rate limiting middleware to all requests.
16app.use((c: Context, next: Next) =>
17  rateLimiter<{ Bindings: Bindings }>({
18    windowMs: 15 * 60 * 1000, // 15 minutes
19    limit: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes).
20    standardHeaders: "draft-6", // draft-6: `RateLimit-*` headers; draft-7: combined `RateLimit` header
21    keyGenerator: (c) => c.req.header("cf-connecting-ip") ?? "", // Method to generate custom identifiers for clients.
22    store: new WorkersKVStore({ namespace: c.env.CACHE }), // Here CACHE is your WorkersKV Binding.
23  })(c, next)
24);

Using DurableObjectStore

1# wrangler.toml
2[[durable_objects.bindings]]
3name = "CACHE"
4class_name = "DurableObjectRateLimiter"
5
6[[migrations]]
7tag = "v1" # Should be unique for each entry
8new_classes = ["DurableObjectRateLimiter"]

For more info on setting up your Durable Objects you can check out Get Started Guide on cloudflare.

1// index.ts
2import { DurableObjectStore, DurableObjectRateLimiter } from "@hono-rate-limiter/cloudflare";
3import { rateLimiter } from "hono-rate-limiter";
4import { Context, Next } from "hono";
5import { DurableObjectNamespace } from "cloudflare:worker";
6
7// Add this in Hono app
8type Bindings = {
9  CACHE: DurableObjectNamespace<DurableObjectRateLimiter>;
10  // ... other binding types
11};
12
13const app = new Hono<{ Bindings: Bindings }>();
14
15// Apply the rate limiting middleware to all requests.
16app.use((c: Context, next: Next) =>
17  rateLimiter<{ Bindings: Bindings }>({
18    windowMs: 15 * 60 * 1000, // 15 minutes
19    limit: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes).
20    standardHeaders: "draft-6", // draft-6: `RateLimit-*` headers; draft-7: combined `RateLimit` header
21    keyGenerator: (c) => c.req.header("cf-connecting-ip") ?? "", // Method to generate custom identifiers for clients.
22    store: new DurableObjectStore({ namespace: c.env.CACHE }), // Here CACHE is your Durable Object Binding.
23  })(c, next)
24);
25
26// ...
27
28export { DurableObjectRateLimiter };
29
30export default app;

Configuration Props of WorkersKVStore and DurableObjectStore

namespace

The KV / Durable Object namespace to use. The value you set for <BINDING_NAME> will be used to reference this database / durable object in your Worker.

prefix

The text to prepend to the key in the KV / Durable Object namespace.

Defaults to hrl:.

Contributing

We would love to have more contributors involved!

To get started, please read our Contributing Guide.