@hono-rate-limiter/cloudflare NPM

🔥`@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

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

Usage

Examples

Using `cloudflareRateLimiter`

# wrangler.toml
# The rate limiting API is in open beta.
[[unsafe.bindings]]
name = "MY_RATE_LIMITER"
type = "ratelimit"
# An identifier you define, that is unique to your Cloudflare account.
# Must be an integer.
namespace_id = "1001"

# Limit: the number of tokens allowed within a given period in a single
# Cloudflare location
# Period: the duration of the period, in seconds. Must be either 10 or 60
simple = { limit = 100, period = 60 }

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

import { cloudflareRateLimiter } from "@hono-rate-limiter/cloudflare";

type AppType = {
  Variables: {
    rateLimit: boolean;
  };
  Bindings: {
    RATE_LIMITER: RateLimit;
  };
};

// Apply the rate limiting middleware to all requests.
const app = new Hono<AppType>().use(
  cloudflareRateLimiter<AppType>({
    rateLimitBinding: (c) => c.env.RATE_LIMITER,
    keyGenerator: (c) => c.req.header("cf-connecting-ip") ?? "", // Method to generate custom identifiers for clients.
  })
);

Using `WorkersKVStore`

# wrangler.toml
[[kv_namespaces]]
binding = "CACHE"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

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

// index.ts
import { WorkersKVStore } from "@hono-rate-limiter/cloudflare";
import { rateLimiter } from "hono-rate-limiter";
import { Context, Next } from "hono";
import { KVNamespace } from "cloudflare:worker";

// Add this in Hono app
type Bindings = {
  CACHE: KVNamespace;
  // ... other binding types
};

const app = new Hono<{ Bindings: Bindings }>();

// Apply the rate limiting middleware to all requests.
app.use((c: Context, next: Next) =>
  rateLimiter<{ Bindings: Bindings }>({
    windowMs: 15 * 60 * 1000, // 15 minutes
    limit: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes).
    standardHeaders: "draft-6", // draft-6: `RateLimit-*` headers; draft-7: combined `RateLimit` header
    keyGenerator: (c) => c.req.header("cf-connecting-ip") ?? "", // Method to generate custom identifiers for clients.
    store: new WorkersKVStore({ namespace: c.env.CACHE }), // Here CACHE is your WorkersKV Binding.
  })(c, next)
);

Using `DurableObjectStore`

# wrangler.toml
[[durable_objects.bindings]]
name = "CACHE"
class_name = "DurableObjectRateLimiter"

[[migrations]]
tag = "v1" # Should be unique for each entry
new_classes = ["DurableObjectRateLimiter"]

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

// index.ts
import { DurableObjectStore, DurableObjectRateLimiter } from "@hono-rate-limiter/cloudflare";
import { rateLimiter } from "hono-rate-limiter";
import { Context, Next } from "hono";
import { DurableObjectNamespace } from "cloudflare:worker";

// Add this in Hono app
type Bindings = {
  CACHE: DurableObjectNamespace<DurableObjectRateLimiter>;
  // ... other binding types
};

const app = new Hono<{ Bindings: Bindings }>();

// Apply the rate limiting middleware to all requests.
app.use((c: Context, next: Next) =>
  rateLimiter<{ Bindings: Bindings }>({
    windowMs: 15 * 60 * 1000, // 15 minutes
    limit: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes).
    standardHeaders: "draft-6", // draft-6: `RateLimit-*` headers; draft-7: combined `RateLimit` header
    keyGenerator: (c) => c.req.header("cf-connecting-ip") ?? "", // Method to generate custom identifiers for clients.
    store: new DurableObjectStore({ namespace: c.env.CACHE }), // Here CACHE is your Durable Object Binding.
  })(c, next)
);

// ...

export { DurableObjectRateLimiter };

export 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.