Rate limiting reference
Arcjet rate limiting allows you to define rules which limit the number of requests a client can make over a period of time.
Configuration
Each rate limit is configured on an exact path with a set of client characteristics and algorithm specific options.
Fixed window rate limit options
Tracks the number of requests made by a client over a fixed time window. Options are explained in the Configuration documentation. See the fixed window algorithm description for more details about how the algorithm works.
// Options for fixed window rate limit// See https://docs.arcjet.com/rate-limiting/configurationtype FixedWindowRateLimitOptions = { // "LIVE" will block requests. "DRY_RUN" will log only mode?: "LIVE" | "DRY_RUN"; // How the client is identified. We recommend setting characteristics on the // Arcjet client rather than per rule. Global characteristics default to the // request IP characteristics?: string[]; // Time window the rate limit applies to window: string; // Maximum number of requests allowed in the time window max: number;};Fixed window example
import { fixedWindow } from "@arcjet/nest";
// ...// This is part of the rules constructed using withRule or a guard// ...fixedWindow({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only window: "60s", // 60 second fixed window max: 100, // allow a maximum of 100 requests});import arcjet, { fixedWindow } from "@arcjet/bun";import { env } from "bun";
const aj = arcjet({ key: env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com rules: [ fixedWindow({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only window: "60s", // 60 second fixed window max: 100, // allow a maximum of 100 requests }), ],});import arcjet, { fixedWindow } from "@arcjet/next";
const aj = arcjet({ key: process.env.ARCJET_KEY!, characteristics: ["ip.src"], // track requests by IP address rules: [ fixedWindow({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only window: "60s", // 60 second fixed window max: 100, // allow a maximum of 100 requests }), ],});import arcjet, { fixedWindow } from "@arcjet/node";
const aj = arcjet({ key: process.env.ARCJET_KEY!, characteristics: ["ip.src"], // track requests by IP address rules: [ fixedWindow({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only window: "60s", // 60 second fixed window max: 100, // allow a maximum of 100 requests }), ],});import arcjet, { fixedWindow } from "@arcjet/remix";
const aj = arcjet({ key: process.env.ARCJET_KEY!, characteristics: ["ip.src"], // track requests by IP address rules: [ fixedWindow({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only window: "60s", // 60 second fixed window max: 100, // allow a maximum of 100 requests }), ],});import arcjet, { fixedWindow } from "@arcjet/sveltekit";
const aj = arcjet({ key: process.env.ARCJET_KEY!, characteristics: ["ip.src"], // track requests by IP address rules: [ fixedWindow({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only window: "60s", // 60 second fixed window max: 100, // allow a maximum of 100 requests }), ],});Sliding window rate limit options
Tracks the number of requests made by a client over a sliding window so that the window moves with time. Options are explained in the Configuration documentation. See the sliding window algorithm description for more details about how the algorithm works.
// Options for sliding window rate limit// See https://docs.arcjet.com/rate-limiting/configurationtype SlidingWindowRateLimitOptions = { // "LIVE" will block requests. "DRY_RUN" will log only mode?: "LIVE" | "DRY_RUN"; // How the client is identified. We recommend setting characteristics on the // Arcjet client rather than per rule. Global characteristics default to the // request IP characteristics?: string[]; // The time interval in seconds for the rate limit interval: number; // Maximum number of requests allowed over the time interval max: number;};Sliding window example
import { slidingWindow } from "@arcjet/nest";
// ...// This is part of the rules constructed using withRule or a guard// ...slidingWindow({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only interval: 60, // 60 second sliding window max: 100, // allow a maximum of 100 requests});import arcjet, { slidingWindow } from "@arcjet/bun";import { env } from "bun";
const aj = arcjet({ key: env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com characteristics: ["ip.src"], // track requests by IP address rules: [ slidingWindow({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only interval: 60, // 60 second sliding window max: 100, // allow a maximum of 100 requests }), ],});import arcjet, { slidingWindow } from "@arcjet/next";
const aj = arcjet({ key: process.env.ARCJET_KEY!, characteristics: ["ip.src"], // track requests by IP address rules: [ slidingWindow({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only interval: 60, // 60 second sliding window max: 100, // allow a maximum of 100 requests }), ],});import arcjet, { slidingWindow } from "@arcjet/node";
const aj = arcjet({ key: process.env.ARCJET_KEY!, characteristics: ["ip.src"], // track requests by IP address rules: [ slidingWindow({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only interval: 60, // 60 second sliding window max: 100, // allow a maximum of 100 requests }), ],});import arcjet, { slidingWindow } from "@arcjet/remix";
const aj = arcjet({ key: process.env.ARCJET_KEY!, characteristics: ["ip.src"], // track requests by IP address rules: [ slidingWindow({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only interval: 60, // 60 second sliding window max: 100, // allow a maximum of 100 requests }), ],});import arcjet, { slidingWindow } from "@arcjet/sveltekit";
const aj = arcjet({ key: process.env.ARCJET_KEY!, characteristics: ["ip.src"], // track requests by IP address rules: [ slidingWindow({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only interval: 60, // 60 second sliding window max: 100, // allow a maximum of 100 requests }), ],});Token bucket rate limit options
Based on a bucket filled with a specific number of tokens. Each request withdraws a token from the bucket and the bucket is refilled at a fixed rate. Once the bucket is empty, the client is blocked until the bucket refills. Options are explained in the Configuration documentation. See the token bucket algorithm description for more details about how the algorithm works.
// Options for token bucket rate limit// See https://docs.arcjet.com/rate-limiting/configurationtype TokenBucketRateLimitOptions = { // "LIVE" will block requests. "DRY_RUN" will log only mode?: "LIVE" | "DRY_RUN"; // How the client is identified. We recommend setting characteristics on the // Arcjet client rather than per rule. Global characteristics default to the // request IP characteristics?: string[]; // Number of tokens to add to the bucket at each interval refillRate: number; // The interval in seconds to add tokens to the bucket interval: number; // The maximum number of tokens the bucket can hold capacity: number;};Token bucket example
See the token bucket request example for how to specify the number of tokens to request.
import { tokenBucket } from "@arcjet/nest";
// ...// This is part of the rules constructed using withRule or a guard// ...tokenBucket({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only refillRate: 10, // refill 10 tokens per interval interval: 60, // 60 second interval capacity: 100, // bucket maximum capacity of 100 tokens});import arcjet, { tokenBucket } from "@arcjet/bun";import { env } from "bun";
const aj = arcjet({ key: env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com characteristics: ["ip.src"], // track requests by IP address rules: [ tokenBucket({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only refillRate: 10, // refill 10 tokens per interval interval: 60, // 60 second interval capacity: 100, // bucket maximum capacity of 100 tokens }), ],});import arcjet, { tokenBucket } from "@arcjet/next";
const aj = arcjet({ key: process.env.ARCJET_KEY!, characteristics: ["ip.src"], // track requests by IP address rules: [ tokenBucket({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only refillRate: 10, // refill 10 tokens per interval interval: 60, // 60 second interval capacity: 100, // bucket maximum capacity of 100 tokens }), ],});import arcjet, { tokenBucket } from "@arcjet/node";
const aj = arcjet({ key: process.env.ARCJET_KEY!, characteristics: ["ip.src"], // track requests by IP address rules: [ tokenBucket({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only refillRate: 10, // refill 10 tokens per interval interval: 60, // 60 second interval capacity: 100, // bucket maximum capacity of 100 tokens }), ],});import arcjet, { tokenBucket } from "@arcjet/remix";
const aj = arcjet({ key: process.env.ARCJET_KEY!, characteristics: ["ip.src"], // track requests by IP address rules: [ tokenBucket({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only refillRate: 10, // refill 10 tokens per interval interval: 60, // 60 second interval capacity: 100, // bucket maximum capacity of 100 tokens }), ],});import arcjet, { tokenBucket } from "@arcjet/sveltekit";
const aj = arcjet({ key: process.env.ARCJET_KEY!, characteristics: ["ip.src"], // track requests by IP address rules: [ tokenBucket({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only refillRate: 10, // refill 10 tokens per interval interval: 60, // 60 second interval capacity: 100, // bucket maximum capacity of 100 tokens }), ],});Identifying users
Rate limit rules use characteristics to identify the client and apply the
limit across requests. The default is to use the client’s IP address. However,
you can specify other
characteristics such as a user
ID or other metadata from your application.
In this example we define a rate limit rule that applies to a specific user ID.
The custom characteristic is userId with the value passed as a prop on the
protect function. You can use any string for the characteristic name and any
string, number or boolean for the value.
import arcjet, { fixedWindow } from "@arcjet/bun";import { env } from "bun";
const aj = arcjet({ key: env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com // Define a custom userId characteristic. // See https://docs.arcjet.com/rate-limiting/configuration#characteristics characteristics: ["userId"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default { port: 3000, fetch: aj.handler(async (req) => { // Pass userId as a string to identify the user. This could also be a number // or boolean value const decision = await aj.protect(req, { userId: "user123" }); console.log("Arcjet decision", decision);
if (decision.isDenied()) { return new Response("Too many requests", { status: 429 }); } return new Response("Hello world"); }),};import arcjet, { fixedWindow } from "@arcjet/bun";import { env } from "bun";
const aj = arcjet({ key: env.ARCJET_KEY, // Get your site key from https://app.arcjet.com // Define a custom userId characteristic. // See https://docs.arcjet.com/rate-limiting/configuration#characteristics characteristics: ["userId"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default { port: 3000, fetch: aj.handler(async (req) => { // Pass userId as a string to identify the user. This could also be a number // or boolean value const decision = await aj.protect(req, { userId: "user123" }); console.log("Arcjet decision", decision);
if (decision.isDenied()) { return new Response("Too many requests", { status: 429 }); } return new Response("Hello world"); }),};import arcjet, { fixedWindow } from "@arcjet/remix";import type { LoaderFunctionArgs } from "@remix-run/node";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com // Define a custom userId characteristic. // See https://docs.arcjet.com/rate-limiting/configuration#characteristics characteristics: ["userId"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function loader(args: LoaderFunctionArgs) { // Pass userId as a string to identify the user. This could also be a number // or boolean value const decision = await aj.protect(args, { userId: "user123" });
if (decision.isDenied()) { throw new Response("Forbidden", { status: 403, statusText: "Forbidden" }); }
return null;}import arcjet, { fixedWindow } from "@arcjet/remix";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Get your site key from https://app.arcjet.com // Define a custom userId characteristic. // See https://docs.arcjet.com/rate-limiting/configuration#characteristics characteristics: ["userId"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function loader(args) { // Pass userId as a string to identify the user. This could also be a number // or boolean value const decision = await aj.protect(args, { userId: "user123" });
if (decision.isDenied()) { throw new Response("Forbidden", { status: 403, statusText: "Forbidden" }); }
return null;}import { env } from "$env/dynamic/private";import arcjet, { fixedWindow } from "@arcjet/sveltekit";import { error, json, type RequestEvent } from "@sveltejs/kit";
const aj = arcjet({ key: env.ARCJET_KEY!, // Define a custom userId characteristic. // See https://docs.arcjet.com/architecture#custom-characteristics characteristics: ["userId"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(event: RequestEvent) { // Pass userId as a string to identify the user. This could also be a number // or boolean value. const decision = await aj.protect(event, { userId: "user123" });
if (decision.isDenied()) { return error(429, { message: "Too many requests" }); }
return json({ message: "Hello world" });}import { env } from "$env/dynamic/private";import arcjet, { fixedWindow } from "@arcjet/sveltekit";import { error, json } from "@sveltejs/kit";
const aj = arcjet({ key: env.ARCJET_KEY, // Define a custom userId characteristic. // See https://docs.arcjet.com/architecture#custom-characteristics characteristics: ["userId"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(event) { // Pass userId as a string to identify the user. This could also be a number // or boolean value. const decision = await aj.protect(event, { userId: "user123" });
if (decision.isDenied()) { return error(429, { message: "Too many requests" }); }
return json({ message: "Hello world" });}import arcjet, { fixedWindow } from "@arcjet/next";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Define a custom userId characteristic. // See https://docs.arcjet.com/architecture#custom-characteristics characteristics: ["userId"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default async function handler(req, res) { // Pass userId as a string to identify the user. This could also be a number // or boolean value. const decision = await aj.protect(req, { userId: "user123" });
if (decision.isDenied()) { return res.status(429).json({ error: "Too Many Requests" }); }
res.status(200).json({ name: "Hello world" });}import arcjet, { fixedWindow } from "@arcjet/next";import type { NextApiRequest, NextApiResponse } from "next";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Define a custom userId characteristic. // See https://docs.arcjet.com/architecture#custom-characteristics characteristics: ["userId"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default async function handler( req: NextApiRequest, res: NextApiResponse,) { // Pass userId as a string to identify the user. This could also be a number // or boolean value. const decision = await aj.protect(req, { userId: "user123" });
if (decision.isDenied()) { return res.status(429).json({ error: "Too Many Requests" }); }
res.status(200).json({ name: "Hello world" });}import arcjet, { fixedWindow } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Define a custom userId characteristic. // See https://docs.arcjet.com/architecture#custom-characteristics characteristics: ["userId"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(req: Request) { // Pass userId as a string to identify the user. This could also be a number // or boolean value. const decision = await aj.protect(req, { userId: "user123" });
if (decision.isDenied()) { return NextResponse.json( { error: "Too Many Requests", reason: decision.reason, }, { status: 429, }, ); }
return NextResponse.json({ message: "Hello world", });}import arcjet, { fixedWindow } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Define a custom userId characteristic. // See https://docs.arcjet.com/architecture#custom-characteristics characteristics: ["userId"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(req) { // Pass userId as a string to identify the user. This could also be a number // or boolean value. const decision = await aj.protect(req, { userId: "user123" });
if (decision.isDenied()) { return NextResponse.json( { error: "Too Many Requests", reason: decision.reason, }, { status: 429, }, ); }
return NextResponse.json({ message: "Hello world", });}import arcjet, { fixedWindow } from "@arcjet/node";import http from "node:http";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Get your site key from https://app.arcjet.com // Define a custom userId characteristic. // See https://docs.arcjet.com/rate-limiting/configuration#characteristics characteristics: ["userId"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
const server = http.createServer(async function (req, res) { // Pass userId as a string to identify the user. This could also be a number // or boolean value const decision = await aj.protect(req, { userId: "user123" }); console.log("Arcjet decision", decision);
if (decision.isDenied()) { res.writeHead(429, { "Content-Type": "application/json" }); res.end( JSON.stringify({ error: "Too Many Requests", reason: decision.reason }), ); } else { res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ message: "Hello world" })); }});
server.listen(8000);import arcjet, { fixedWindow } from "@arcjet/node";import http from "node:http";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com // Define a custom userId characteristic. // See https://docs.arcjet.com/rate-limiting/configuration#characteristics characteristics: ["userId"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
const server = http.createServer(async function ( req: http.IncomingMessage, res: http.ServerResponse,) { // Pass userId as a string to identify the user. This could also be a number // or boolean value const decision = await aj.protect(req, { userId: "user123" }); console.log("Arcjet decision", decision);
if (decision.isDenied()) { res.writeHead(429, { "Content-Type": "application/json" }); res.end( JSON.stringify({ error: "Too Many Requests", reason: decision.reason }), ); } else { res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ message: "Hello world" })); }});
server.listen(8000);import { ARCJET, type ArcjetNest, fixedWindow } from "@arcjet/nest";import { Controller, Get, HttpException, HttpStatus, Inject, Injectable, Req,} from "@nestjs/common";import type { Request } from "express";
// This would normally go in your service file e.g.// src/page/page.service.ts@Injectable()export class PageAdvancedService { message(): { message: string } { return { message: "Hello world", }; }}
// This would normally go in your controller file e.g.// src/page/page.controller.ts@Controller("page")// Sets up the Arcjet protection without using a guard so we can access the// decision and use it in the controller.export class PageAdvancedController { constructor( private readonly pageService: PageAdvancedService, @Inject(ARCJET) private readonly arcjet: ArcjetNest, ) {}
@Get() async index(@Req() req: Request) { const decision = await this.arcjet .withRule( fixedWindow({ // characteristics can also be set on the client in app.module.ts characteristics: ["userId"], mode: "LIVE", window: "1h", max: 60, }), ) .protect(req, { userId: "user123" });
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new HttpException( "Too many requests", HttpStatus.TOO_MANY_REQUESTS, ); } else { throw new HttpException("Forbidden", HttpStatus.FORBIDDEN); } }
return this.pageService.message(); }}To identify users with different characteristics e.g. IP address for anonymous users and a user ID for logged in users, you can create a custom fingerprint. See the example in the custom characteristics section.
Loader vs action
Remix does not support middleware, instead they recommend calling functions directly inside the loader. Loaders execute before the page is loaded.
All our examples use this pattern, but you can also execute Arcjet in an
action. This would be appropriate
to protect a form submission or other non-GET request.
For example, you might want to run rate limiting on every GET page load, but
use rate limiting and email validation in an action handling a form POST.
Action
This example shows how to run Arcjet in a Remix action:
import arcjet, { detectBot } from "@arcjet/remix";import type { ActionFunctionArgs } from "@remix-run/node";import { redirect } from "@remix-run/node";
const aj = arcjet({ key: process.env.ARCJET_KEY!, rules: [ detectBot({ mode: "LIVE", // configured with a list of bots to allow from // https://arcjet.com/bot-list - all other detected bots will be blocked allow: [ // Google has multiple crawlers, each with a different user-agent, so we // allow the entire Google category "CATEGORY:GOOGLE", "CURL", // allows the default user-agent of the `curl` tool "DISCORD_CRAWLER", // allows Discordbot ], }), ],});
export async function action(args: ActionFunctionArgs) { const decision = await aj.protect(args);
if (decision.isDenied()) { // This redirects to a generic error page (which you should create), but you // could also throw an error return redirect(`/error`); }
// ... // Process the action here // ...
return null;}import arcjet, { detectBot } from "@arcjet/remix";import { redirect } from "@remix-run/node";
const aj = arcjet({ key: process.env.ARCJET_KEY, rules: [ detectBot({ mode: "LIVE", // configured with a list of bots to allow from // https://arcjet.com/bot-list - all other detected bots will be blocked allow: [ // Google has multiple crawlers, each with a different user-agent, so we // allow the entire Google category "CATEGORY:GOOGLE", "CURL", // allows the default user-agent of the `curl` tool "DISCORD_CRAWLER", // allows Discordbot ], }), ],});
export async function action(args) { const decision = await aj.protect(args);
if (decision.isDenied()) { // This redirects to a generic error page (which you should create), but you // could also throw an error return redirect(`/error`); }
// ... // Process the action here // ...
return null;}Guards and routes
Arcjet can be integrated into NestJS in several places using NestJS guards or directly within the route controller:
- Global guard: Applies Arcjet rules on every request, but does not allow you to configure rules per route.
- Per route guard: Allows you to configure rules per route, but requires you to add the guard to every route and has limited flexibility.
- Within route: Requires some code duplication, but allows maximum flexibility because you can customize the rules and response.
Global guard
A global guard can be configured in src/app.module.ts.
import { ArcjetModule, fixedWindow } from "@arcjet/nest";import { Module } from "@nestjs/common";import { ConfigModule } from "@nestjs/config";
@Module({ imports: [ ConfigModule.forRoot({ isGlobal: true, envFilePath: ".env.local", }), ArcjetModule.forRoot({ isGlobal: true, key: process.env.ARCJET_KEY!, rules: [ // Applies to every request fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ], }), // ... other modules ],})export class AppModule {}This can then be added to the controller for all the routes you wish to protect with Arcjet.
import { ArcjetGuard } from "@arcjet/nest";import { Controller, Get, Injectable, UseGuards } from "@nestjs/common";
// This would normally go in your controller file e.g.// src/page/page.controller.ts@Controller("page")// Uses the ArcjetGuard to protect the controller with the default rules defined// in app.module.ts. Using a guard makes it easy to apply Arcjet rules, but you// don't get access to the decision.@UseGuards(ArcjetGuard)export class PageController { constructor(private readonly pageService: PageService) {}
@Get() index() { return this.pageService.message(); }}
// This would normally go in your service file e.g.// src/page/page.service.ts@Injectable()export class PageService { message(): { message: string } { return { message: "Hello world", }; }}Per route guard
A per route guard can be configured in the controller for each route you wish to
protect with specific Arcjet rules. The client created in src/app.module.ts
is automatically passed to the guard.
The rules will be applied and a generic error returned if the result is DENY.
import { WithArcjetRules, fixedWindow } from "@arcjet/nest";import { Injectable, Get } from "@nestjs/common";
// This would normally go in your controller file e.g.// src/page/page.controller.ts// Attaches the ArcjetGuard to the controller to protect it with the specified// rules extended from the global rules defined in app.module.ts.@WithArcjetRules([ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }),])export class PageController { constructor(private readonly pageService: PageService) {}
@Get() index() { return this.pageService.message(); }}
// This would normally go in your service file e.g.// src/page/page.service.ts@Injectable()export class PageService { message(): { message: string } { return { message: "Hello world", }; }}Within route
Call Arcjet from within the route controller to have maximum flexibility.
import { ARCJET, type ArcjetNest, fixedWindow } from "@arcjet/nest";import { Controller, Get, HttpException, HttpStatus, Inject, Injectable, Req,} from "@nestjs/common";import type { Request } from "express";
// This would normally go in your service file e.g.// src/page/page.service.ts@Injectable()export class PageAdvancedService { message(): { message: string } { return { message: "Hello world", }; }}
// This would normally go in your controller file e.g.// src/page/page.controller.ts@Controller("page")// Sets up the Arcjet protection without using a guard so we can access the// decision and use it in the controller.export class PageAdvancedController { constructor( private readonly pageService: PageAdvancedService, @Inject(ARCJET) private readonly arcjet: ArcjetNest, ) {}
@Get() async index(@Req() req: Request) { const decision = await this.arcjet .withRule( fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ) .protect(req);
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new HttpException( "Too many requests", HttpStatus.TOO_MANY_REQUESTS, ); } else { throw new HttpException("Forbidden", HttpStatus.FORBIDDEN); } }
return this.pageService.message(); }}Per route vs middleware
Bot protection rules can be configured in two ways:
- Per API route: The rule is defined in the API route itself. This allows you to configure the rule alongside the code it is protecting which is useful if you want to use the decision to add context to your own code. However, it means rules are not located in a single place.
- Middleware: The rule is defined in the middleware. This allows you to configure rules in a single place or apply them globally to all routes, but it means the rules are not located alongside the code they are protecting.
Per route
This configures bot protection on a single route.
import arcjet, { detectBot } from "@arcjet/next";
const aj = arcjet({ key: process.env.ARCJET_KEY, rules: [ detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export default async function handler(req, res) { const decision = await aj.protect(req);
if (decision.isDenied() && decision.reason.isBot()) { return res.status(403).json({ error: "You are a bot!" }); }
// Arcjet Pro plan verifies the authenticity of common bots using IP data. // Verification isn't always possible, so we recommend checking the decision // separately. // https://docs.arcjet.com/bot-protection/reference#bot-verification if (decision.reason.isBot() && decision.reason.isSpoofed()) { return res.status(403).json({ error: "You are a bot!" }); }
res.status(200).json({ name: "Hello world" });}import arcjet, { detectBot } from "@arcjet/next";import type { NextApiRequest, NextApiResponse } from "next";
const aj = arcjet({ key: process.env.ARCJET_KEY!, rules: [ detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export default async function handler( req: NextApiRequest, res: NextApiResponse,) { const decision = await aj.protect(req);
if (decision.isDenied() && decision.reason.isBot()) { return res.status(403).json({ error: "You are a bot!" }); }
// Arcjet Pro plan verifies the authenticity of common bots using IP data. // Verification isn't always possible, so we recommend checking the decision // separately. // https://docs.arcjet.com/bot-protection/reference#bot-verification if (decision.reason.isBot() && decision.reason.isSpoofed()) { return res.status(403).json({ error: "You are a bot!" }); }
res.status(200).json({ name: "Hello world" });}import arcjet, { detectBot } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY!, rules: [ detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export async function GET(req: Request) { const decision = await aj.protect(req);
if (decision.isDenied() && decision.reason.isBot()) { return NextResponse.json( { error: "You are a bot!", }, { status: 403 }, ); }
// Arcjet Pro plan verifies the authenticity of common bots using IP data. // Verification isn't always possible, so we recommend checking the decision // separately. // https://docs.arcjet.com/bot-protection/reference#bot-verification if (decision.reason.isBot() && decision.reason.isSpoofed()) { return NextResponse.json( { error: "You are a bot!", }, { status: 403 }, ); }
return NextResponse.json({ message: "Hello world", });}import arcjet, { detectBot } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY, rules: [ detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export async function GET(req) { const decision = await aj.protect(req);
if (decision.isDenied() && decision.reason.isBot()) { return NextResponse.json( { error: "You are a bot!", }, { status: 403 }, ); }
// Arcjet Pro plan verifies the authenticity of common bots using IP data. // Verification isn't always possible, so we recommend checking the decision // separately. // https://docs.arcjet.com/bot-protection/reference#bot-verification if (decision.reason.isBot() && decision.reason.isSpoofed()) { return NextResponse.json( { error: "You are a bot!", }, { status: 403 }, ); }
return NextResponse.json({ message: "Hello world", });}Middleware
This will run on every request to your Next.js app, except for static assets
(configured in the matcher - see the Next.js
docs
for details).
Create a file called middleware.ts in your project root (at the same level as
pages or app or inside src):
import arcjet, { createMiddleware, detectBot } from "@arcjet/next";export const config = { // matcher tells Next.js which routes to run the middleware on. // This runs the middleware on all routes except for static assets. matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],};const aj = arcjet({ key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com rules: [ detectBot({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only // Block all bots except the following allow: [ "CATEGORY:SEARCH_ENGINE", // Google, Bing, etc // Uncomment to allow these other common bot categories // See the full list at https://arcjet.com/bot-list //"CATEGORY:MONITOR", // Uptime monitoring services //"CATEGORY:PREVIEW", // Link previews e.g. Slack, Discord ], }), ],});// Pass any existing middleware with the optional existingMiddleware propexport default createMiddleware(aj);You can also customize the response depending on the decision. In this case we will return a 403 Forbidden response only if we detect a hosting provider IP address for the bot detection rule result:
import arcjet, { detectBot } from "@arcjet/next";import { NextRequest, NextResponse } from "next/server";
export const config = { // matcher tells Next.js which routes to run the middleware on. // This runs the middleware on all routes except for static assets. matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],};const aj = arcjet({ key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com rules: [ detectBot({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only allow: [], // "allow none" will block all detected bots }), ],});
export default async function middleware(request: NextRequest) { const decision = await aj.protect(request);
if ( // If the decision is deny because the request is from a bot and the bot IP // address is from a known hosting provider, then block the request decision.isDenied() && decision.reason.isBot() && decision.ip.isHosting() ) { return NextResponse.json({ error: "Forbidden" }, { status: 403 }); } else { return NextResponse.next(); }}Create a file called middleware.js in your project root (at the same level as
pages or app or inside src):
import arcjet, { createMiddleware, detectBot } from "@arcjet/next";export const config = { // matcher tells Next.js which routes to run the middleware on. // This runs the middleware on all routes except for static assets. matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],};const aj = arcjet({ key: process.env.ARCJET_KEY, // Get your site key from https://app.arcjet.com rules: [ detectBot({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only // Block all bots except the following allow: [ "CATEGORY:SEARCH_ENGINE", // Google, Bing, etc // Uncomment to allow these other common bot categories // See the full list at https://arcjet.com/bot-list //"CATEGORY:MONITOR", // Uptime monitoring services //"CATEGORY:PREVIEW", // Link previews e.g. Slack, Discord ], }), ],});// Pass any existing middleware with the optional existingMiddleware propexport default createMiddleware(aj);You can also customize the response depending on the decision. In this case we will return a 403 Forbidden response only if we detect a hosting provider IP address for the bot detection rule result:
import arcjet, { detectBot } from "@arcjet/next";import { NextResponse } from "next/server";
export const config = { // matcher tells Next.js which routes to run the middleware on. // This runs the middleware on all routes except for static assets. matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],};const aj = arcjet({ key: process.env.ARCJET_KEY, // Get your site key from https://app.arcjet.com rules: [ detectBot({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only allow: [], // "allow none" will block all detected bots }), ],});
export default async function middleware(request) { const decision = await aj.protect(request);
if ( // If the decision is deny because the request is from a bot and the bot IP // address is from a known hosting provider, then block the request decision.isDenied() && decision.reason.isBot() && decision.ip.isHosting() ) { return NextResponse.json({ error: "Forbidden" }, { status: 403 }); } else { return NextResponse.next(); }}Avoiding double protection with middleware
If you use Arcjet in middleware and individual routes, you need to be careful that Arcjet is not running multiple times per request. This can be avoided by excluding the API route from the middleware matcher.
For example, if you already have a bot detection rule defined in the API route
at /api/hello, you can exclude it from the middleware by specifying a matcher
in /middleware.ts:
import arcjet, { createMiddleware, detectBot } from "@arcjet/next";export const config = { // The matcher prevents the middleware executing on static assets and the // /api/hello API route because you already installed Arcjet directly matcher: ["/((?!_next/static|_next/image|favicon.ico|api/hello).*)"],};const aj = arcjet({ key: process.env.ARCJET_KEY!, rules: [ detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});// Pass any existing middleware with the optional existingMiddleware propexport default createMiddleware(aj);Pages & Server Actions
Arcjet can be used inside Next.js middleware, API routes, pages, server components, and server actions. Client components cannot be protected because they run on the client only.
See the Next.js SDK reference for examples of pages / page components and server actions.
Per route vs hooks
Bot protection rules can be configured in two ways:
- Per route: The rule is defined in the route handler itself. This allows you to configure the rule alongside the code it is protecting which is useful if you want to use the decision to add context to your own code. However, it means rules are not located in a single place.
- Hooks: The rule is defined as a hook. This allows you to configure rules in a single place or apply them globally to all routes, but it means the rules are not located alongside the code they are protecting.
Per route
This configures bot protection on a single route.
import { env } from "$env/dynamic/private";import arcjet, { detectBot } from "@arcjet/sveltekit";import { error, json, type RequestEvent } from "@sveltejs/kit";
const aj = arcjet({ key: env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com rules: [ detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export async function GET(event: RequestEvent) { const decision = await aj.protect(event);
if (decision.isDenied()) { return error(403, { message: "Forbidden" }); }
return json({ message: "Hello world" });}import { env } from "$env/dynamic/private";import arcjet, { detectBot } from "@arcjet/sveltekit";import { error, json } from "@sveltejs/kit";
const aj = arcjet({ key: env.ARCJET_KEY, // Get your site key from https://app.arcjet.com rules: [ detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export async function GET(event) { const decision = await aj.protect(event);
if (decision.isDenied()) { return error(403, { message: "Forbidden" }); }
return json({ message: "Hello world" });}Hooks
This will run on every request to your SvelteKit app - see the SvelteKit Hooks docs for details.
import { env } from "$env/dynamic/private";import arcjet, { detectBot } from "@arcjet/sveltekit";import { error } from "@sveltejs/kit";
const aj = arcjet({ key: env.ARCJET_KEY, // Get your site key from https://app.arcjet.com rules: [ detectBot({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only // Block all bots except the following allow: [ "CATEGORY:SEARCH_ENGINE", // Google, Bing, etc // Uncomment to allow these other common bot categories // See the full list at https://arcjet.com/bot-list //"CATEGORY:MONITOR", // Uptime monitoring services //"CATEGORY:PREVIEW", // Link previews e.g. Slack, Discord ], }), ],});
export async function handle({ event, resolve }) { const decision = await aj.protect(event);
// Bots not in the allow list will be blocked if (decision.isDenied()) { return error(403, "Forbidden"); }
// Arcjet Pro plan verifies the authenticity of common bots using IP data. // Verification isn't always possible, so we recommend checking the decision // separately. // https://docs.arcjet.com/bot-protection/reference#bot-verification if (decision.reason.isBot() && decision.reason.isSpoofed()) { return error(403, "You are a bot!"); }
return resolve(event);}import { env } from "$env/dynamic/private";import arcjet, { detectBot } from "@arcjet/sveltekit";import { error, type RequestEvent } from "@sveltejs/kit";
const aj = arcjet({ key: env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com rules: [ detectBot({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only // Block all bots except the following allow: [ "CATEGORY:SEARCH_ENGINE", // Google, Bing, etc // Uncomment to allow these other common bot categories // See the full list at https://arcjet.com/bot-list //"CATEGORY:MONITOR", // Uptime monitoring services //"CATEGORY:PREVIEW", // Link previews e.g. Slack, Discord ], }), ],});
export async function handle({ event, resolve,}: { event: RequestEvent; resolve: (event: RequestEvent) => Response | Promise<Response>;}): Promise<Response> { const decision = await aj.protect(event);
// Bots not in the allow list will be blocked if (decision.isDenied()) { return error(403, "Forbidden"); }
// Arcjet Pro plan verifies the authenticity of common bots using IP data. // Verification isn't always possible, so we recommend checking the decision // separately. // https://docs.arcjet.com/bot-protection/reference#bot-verification if (decision.reason.isBot() && decision.reason.isSpoofed()) { return error(403, "You are a bot!"); }
return resolve(event);}Avoiding double protection with hooks
If you use Arcjet in hooks and individual routes, you need to be careful that Arcjet is not running multiple times per request. This can be avoided by excluding the individual routes before running Arcjet in the hook.
For example, if you already have rules defined in the API route
at /api/arcjet, you can exclude it from the hook like this:
import { env } from "$env/dynamic/private";import arcjet, { detectBot } from "@arcjet/sveltekit";import { error, type RequestEvent } from "@sveltejs/kit";
const aj = arcjet({ key: env.ARCJET_KEY!, rules: [ detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export async function handle({ event, resolve,}: { event: RequestEvent; resolve: (event: RequestEvent) => Response | Promise<Response>;}): Promise<Response> { // Ignore routes that extend the Arcjet rules // - they will call `.protect` themselves const filteredRoutes = ["/api/arcjet"]; if (filteredRoutes.includes(event.url.pathname)) { // return - route will handle protecttion return resolve(event); }
const decision = await aj.protect(event);
if (decision.isDenied()) { return error(403, "Forbidden"); }
return resolve(event);}Decision
Arcjet provides a single protect function that is used to execute your
protection rules. This requires a RequestEvent property which is the event
context as passed to the request handler.
If you are using a global guard or per route
guard then protect is called for you behind the scenes. If you add Arcjet
within a route then you call it directly.
This function returns a Promise that resolves to an
ArcjetDecision object. This contains the following properties:
id(string) - The unique ID for the request. This can be used to look up the request in the Arcjet dashboard. It is prefixed withreq_for decisions involving the Arcjet cloud API. For decisions taken locally, the prefix islreq_.conclusion(ArcjetConclusion) - The final conclusion based on evaluating each of the configured rules. If you wish to accept Arcjet’s recommended action based on the configured rules then you can use this property.reason(ArcjetReason) - An object containing more detailed information about the conclusion.results(ArcjetRuleResult[]) - An array ofArcjetRuleResultobjects containing the results of each rule that was executed.ip(ArcjetIpDetails) - An object containing Arcjet’s analysis of the client IP address. See the SDK reference for more information.
You check if a deny conclusion has been returned by a rate limit rule by using
decision.isDenied() and decision.reason.isRateLimit().
You can iterate through the results and check whether a rate limit was applied:
for (const result of decision.results) { console.log("Rule Result", result);}This example will log the full result as well as each rate limit rule:
import arcjet, { detectBot, fixedWindow } from "@arcjet/bun";import { env } from "bun";
const aj = arcjet({ key: env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export default { port: 3000, fetch: aj.handler(async (req) => { const decision = await aj.protect(req);
for (const result of decision.results) { console.log("Rule Result", result);
if (result.reason.isRateLimit()) { console.log("Rate limit rule", result); }
if (result.reason.isBot()) { console.log("Bot protection rule", result); } }
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { return new Response("Too many requests", { status: 429 }); } else { return new Response("Forbidden", { status: 403 }); } }
return new Response("Hello world"); }),};import arcjet, { detectBot, fixedWindow } from "@arcjet/bun";import { env } from "bun";
const aj = arcjet({ key: env.ARCJET_KEY, // Get your site key from https://app.arcjet.com characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export default { port: 3000, fetch: aj.handler(async (req) => { const decision = await aj.protect(req);
for (const result of decision.results) { console.log("Rule Result", result);
if (result.reason.isRateLimit()) { console.log("Rate limit rule", result); }
if (result.reason.isBot()) { console.log("Bot protection rule", result); } }
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { return new Response("Too many requests", { status: 429 }); } else { return new Response("Forbidden", { status: 403 }); } }
return new Response("Hello world"); }),};import arcjet, { fixedWindow, detectBot } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export async function POST(req: Request) { const decision = await aj.protect(req);
for (const result of decision.results) { console.log("Rule Result", result);
if (result.reason.isRateLimit()) { console.log("Rate limit rule", result); }
if (result.reason.isBot()) { console.log("Bot protection rule", result); } }
if (decision.isDenied()) { return NextResponse.json({ error: "Forbidden" }, { status: 403 }); }
return NextResponse.json({ message: "Hello world", });}import arcjet, { fixedWindow, detectBot } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export async function POST(req) { const decision = await aj.protect(req);
for (const result of decision.results) { console.log("Rule Result", result);
if (result.reason.isRateLimit()) { console.log("Rate limit rule", result); }
if (result.reason.isBot()) { console.log("Bot protection rule", result); } }
if (decision.isDenied()) { return NextResponse.json({ error: "Forbidden" }, { status: 403 }); }
return NextResponse.json({ message: "Hello world", });}import arcjet, { fixedWindow, detectBot } from "@arcjet/next";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export default async function handler(req, res) { const decision = await aj.protect(req); console.log("Decision", decision);
for (const result of decision.results) { console.log("Rule Result", result);
if (result.reason.isRateLimit()) { console.log("Rate limit rule", result); }
if (result.reason.isBot()) { console.log("Bot protection rule", result); } }
if (decision.isDenied()) { return res .status(403) .json({ error: "Forbidden", reason: decision.reason }); }
res.status(200).json({ name: "Hello world" });}import arcjet, { fixedWindow, detectBot } from "@arcjet/next";import type { NextApiRequest, NextApiResponse } from "next";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export default async function handler( req: NextApiRequest, res: NextApiResponse,) { const decision = await aj.protect(req); console.log("Decision", decision);
for (const result of decision.results) { console.log("Rule Result", result);
if (result.reason.isRateLimit()) { console.log("Rate limit rule", result); }
if (result.reason.isBot()) { console.log("Bot protection rule", result); } }
if (decision.isDenied()) { return res .status(403) .json({ error: "Forbidden", reason: decision.reason }); }
res.status(200).json({ name: "Hello world" });}import { env } from "$env/dynamic/private";import arcjet, { detectBot, fixedWindow } from "@arcjet/sveltekit";import { error, json, type RequestEvent } from "@sveltejs/kit";
const aj = arcjet({ key: env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export async function GET(event: RequestEvent) { const decision = await aj.protect(event);
for (const result of decision.results) { console.log("Rule Result", result);
if (result.reason.isRateLimit()) { console.log("Rate limit rule", result); }
if (result.reason.isBot()) { console.log("Bot protection rule", result); } }
if (decision.isDenied()) { return error(403, "Forbidden"); }
return json({ message: "Hello world" });}import { env } from "$env/dynamic/private";import arcjet, { detectBot, fixedWindow } from "@arcjet/sveltekit";import { error, json } from "@sveltejs/kit";
const aj = arcjet({ key: env.ARCJET_KEY, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export async function GET(event) { const decision = await aj.protect(event);
for (const result of decision.results) { console.log("Rule Result", result);
if (result.reason.isRateLimit()) { console.log("Rate limit rule", result); }
if (result.reason.isBot()) { console.log("Bot protection rule", result); } }
if (decision.isDenied()) { return error(403, "Forbidden"); }
return json({ message: "Hello world" });}import arcjet, { fixedWindow, detectBot } from "@arcjet/remix";import type { LoaderFunctionArgs } from "@remix-run/node";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export async function loader(args: LoaderFunctionArgs) { const decision = await aj.protect(args);
for (const result of decision.results) { console.log("Rule Result", result);
if (result.reason.isRateLimit()) { console.log("Rate limit rule", result); }
if (result.reason.isBot()) { console.log("Bot protection rule", result); } }
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new Response("Too Many Requests", { status: 429, statusText: "Too Many Requests", }); } else { throw new Response("Forbidden", { status: 403, statusText: "Forbidden" }); } }
return null;}import arcjet, { fixedWindow, detectBot } from "@arcjet/remix";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Get your site key from https://app.arcjet.com characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
export async function loader(args) { const decision = await aj.protect(args);
for (const result of decision.results) { console.log("Rule Result", result);
if (result.reason.isRateLimit()) { console.log("Rate limit rule", result); }
if (result.reason.isBot()) { console.log("Bot protection rule", result); } }
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new Response("Too Many Requests", { status: 429, statusText: "Too Many Requests", }); } else { throw new Response("Forbidden", { status: 403, statusText: "Forbidden" }); } }
return null;}import arcjet, { fixedWindow, detectBot } from "@arcjet/node";import http from "node:http";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Get your site key from https://app.arcjet.com characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
const server = http.createServer(async function (req, res) { const decision = await aj.protect(req);
for (const result of decision.results) { console.log("Rule Result", result);
if (result.reason.isRateLimit()) { console.log("Rate limit rule", result); }
if (result.reason.isBot()) { console.log("Bot protection rule", result); } }
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { res.writeHead(429, { "Content-Type": "application/json" }); res.end( JSON.stringify({ error: "Too Many Requests", reason: decision.reason }), ); res.end(JSON.stringify({ error: "Forbidden" })); } else { res.writeHead(403, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "Forbidden" })); } } else { res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ message: "Hello world" })); }});
server.listen(8000);import arcjet, { fixedWindow, detectBot } from "@arcjet/node";import http from "node:http";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), detectBot({ mode: "LIVE", allow: [], // "allow none" will block all detected bots }), ],});
const server = http.createServer(async function ( req: http.IncomingMessage, res: http.ServerResponse,) { const decision = await aj.protect(req);
for (const result of decision.results) { console.log("Rule Result", result);
if (result.reason.isRateLimit()) { console.log("Rate limit rule", result); }
if (result.reason.isBot()) { console.log("Bot protection rule", result); } }
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { res.writeHead(429, { "Content-Type": "application/json" }); res.end( JSON.stringify({ error: "Too Many Requests", reason: decision.reason }), ); res.end(JSON.stringify({ error: "Forbidden" })); } else { res.writeHead(403, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "Forbidden" })); } } else { res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ message: "Hello world" })); }});
server.listen(8000);import { ARCJET, type ArcjetNest, detectBot, fixedWindow } from "@arcjet/nest";import { Controller, Get, HttpException, HttpStatus, Inject, Injectable, Logger, Req,} from "@nestjs/common";import type { Request } from "express";
// This would normally go in your service file e.g.// src/page/page.service.ts@Injectable()export class PageService { message(): { message: string } { return { message: "Hello world", }; }}
// This would normally go in your controller file e.g.// src/page/page.controller.ts@Controller("page")// Sets up the Arcjet protection without using a guard so we can access the// decision and use it in the controller.export class PageController { // Make use of the NestJS logger: https://docs.nestjs.com/techniques/logger // See // https://github.com/arcjet/example-nestjs/blob/ec742e58c8da52d0a399327182c79e3f4edc8f3b/src/app.module.ts#L29 // and https://github.com/arcjet/example-nestjs/blob/main/src/arcjet-logger.ts // for an example of how to connect Arcjet to the NestJS logger private readonly logger = new Logger(PageController.name);
constructor( private readonly pageService: PageService, @Inject(ARCJET) private readonly arcjet: ArcjetNest, ) {}
@Get() async index(@Req() req: Request) { const decision = await this.arcjet .withRule( detectBot({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only // configured with a list of bots to allow from // https://arcjet.com/bot-list allow: [], // blocks all automated clients }), ) .withRule( fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ) .protect(req);
this.logger.log(`Arcjet: id = ${decision.id}`); this.logger.log(`Arcjet: decision = ${decision.conclusion}`);
for (const result of decision.results) { this.logger.log("Rule Result", result);
if (result.reason.isRateLimit()) { this.logger.log("Rate limit rule", result); }
if (result.reason.isBot()) { this.logger.log("Bot protection rule", result); } }
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new HttpException( "Too many requests", HttpStatus.TOO_MANY_REQUESTS, ); } else { throw new HttpException("Forbidden", HttpStatus.FORBIDDEN); } }
return this.pageService.message(); }}Token bucket request
When using a token bucket rule, an additional requested prop should be passed
to the protect function. This is the number of tokens the client is requesting
to withdraw from the bucket.
import arcjet, { tokenBucket } from "@arcjet/bun";import { env } from "bun";
const aj = arcjet({ key: env.ARCJET_KEY, // Get your site key from https://app.arcjet.com characteristics: ["ip.src"], rules: [ tokenBucket({ mode: "LIVE", refillRate: 40_000, interval: "1d", capacity: 40_000, }), ],});
export default { port: 3000, fetch: aj.handler(async (req) => { const decision = await aj.protect(req, { requested: 50 }); console.log("Arcjet decision", decision);
if (decision.isDenied()) { return new Response("Too many requests", { status: 429 }); }
return new Response("Hello world"); }),};import arcjet, { tokenBucket } from "@arcjet/bun";import { env } from "bun";
const aj = arcjet({ key: env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com characteristics: ["ip.src"], rules: [ tokenBucket({ mode: "LIVE", refillRate: 40_000, interval: "1d", capacity: 40_000, }), ],});
export default { port: 3000, fetch: aj.handler(async (req) => { const decision = await aj.protect(req, { requested: 50 }); console.log("Arcjet decision", decision);
if (decision.isDenied()) { return new Response("Too many requests", { status: 429 }); }
return new Response("Hello world"); }),};import arcjet, { tokenBucket } from "@arcjet/remix";import type { LoaderFunctionArgs } from "@remix-run/node";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com characteristics: ["ip.src"], rules: [ tokenBucket({ mode: "LIVE", refillRate: 40_000, interval: "1d", capacity: 40_000, }), ],});
export async function loader(args: LoaderFunctionArgs) { const decision = await aj.protect(args, { requested: 50 });
if (decision.isDenied()) { throw new Response("Forbidden", { status: 403, statusText: "Forbidden" }); }
return null;}import arcjet, { tokenBucket } from "@arcjet/remix";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Get your site key from https://app.arcjet.com characteristics: ["ip.src"], rules: [ tokenBucket({ mode: "LIVE", refillRate: 40_000, interval: "1d", capacity: 40_000, }), ],});
export async function loader(args) { const decision = await aj.protect(args, { requested: 50 });
if (decision.isDenied()) { throw new Response("Forbidden", { status: 403, statusText: "Forbidden" }); }
return null;}import { env } from "$env/dynamic/private";import arcjet, { tokenBucket } from "@arcjet/sveltekit";import { error, json, type RequestEvent } from "@sveltejs/kit";
const aj = arcjet({ key: env.ARCJET_KEY!, characteristics: ["ip.src"], rules: [ tokenBucket({ mode: "LIVE", refillRate: 40_000, interval: "1d", capacity: 40_000, }), ],});
export async function GET(event: RequestEvent) { const decision = await aj.protect(event, { requested: 50 });
if (decision.isDenied()) { return error(429, { message: "Too many requests" }); }
return json({ message: "Hello world" });}import { env } from "$env/dynamic/private";import arcjet, { tokenBucket } from "@arcjet/sveltekit";import { error, json } from "@sveltejs/kit";
const aj = arcjet({ key: env.ARCJET_KEY, characteristics: ["ip.src"], rules: [ tokenBucket({ mode: "LIVE", refillRate: 40_000, interval: "1d", capacity: 40_000, }), ],});
export async function GET(event) { const decision = await aj.protect(event, { requested: 50 });
if (decision.isDenied()) { return error(429, { message: "Too many requests" }); }
return json({ message: "Hello world" });}import arcjet, { tokenBucket } from "@arcjet/next";import type { NextApiRequest, NextApiResponse } from "next";
const aj = arcjet({ key: process.env.ARCJET_KEY!, characteristics: ["ip.src"], rules: [ tokenBucket({ mode: "LIVE", refillRate: 40_000, interval: "1d", capacity: 40_000, }), ],});
export default async function handler( req: NextApiRequest, res: NextApiResponse,) { // Each request will consume 50 tokens const decision = await aj.protect(req, { requested: 50 });
if (decision.isDenied()) { return res.status(429).json({ error: "Too Many Requests" }); }
res.status(200).json({ name: "Hello world" });}import arcjet, { tokenBucket } from "@arcjet/next";import type { NextApiRequest, NextApiResponse } from "next";
const aj = arcjet({ key: process.env.ARCJET_KEY!, characteristics: ["ip.src"], rules: [ tokenBucket({ mode: "LIVE", refillRate: 40_000, interval: "1d", capacity: 40_000, }), ],});
export default async function handler( req: NextApiRequest, res: NextApiResponse,) { // Each request will consume 50 tokens const decision = await aj.protect(req, { requested: 50 });
if (decision.isDenied()) { return res.status(429).json({ error: "Too Many Requests" }); }
res.status(200).json({ name: "Hello world" });}import arcjet, { tokenBucket } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY, characteristics: ["ip.src"], rules: [ tokenBucket({ mode: "LIVE", refillRate: 40_000, interval: "1d", capacity: 40_000, }), ],});
export async function GET(req) { // Each request will consume 50 tokens const decision = await aj.protect(req, { requested: 50 });
if (decision.isDenied()) { return NextResponse.json( { error: "Too Many Requests", reason: decision.reason, }, { status: 429, }, ); }
return NextResponse.json({ message: "Hello world", });}import arcjet, { tokenBucket } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY, characteristics: ["ip.src"], rules: [ tokenBucket({ mode: "LIVE", refillRate: 40_000, interval: "1d", capacity: 40_000, }), ],});
export async function GET(req) { // Each request will consume 50 tokens const decision = await aj.protect(req, { requested: 50 });
if (decision.isDenied()) { return NextResponse.json( { error: "Too Many Requests", reason: decision.reason, }, { status: 429, }, ); }
return NextResponse.json({ message: "Hello world", });}import arcjet, { tokenBucket } from "@arcjet/node";import http from "node:http";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Get your site key from https://app.arcjet.com characteristics: ["ip.src"], rules: [ tokenBucket({ mode: "LIVE", refillRate: 40_000, interval: "1d", capacity: 40_000, }), ],});
const server = http.createServer(async function (req, res) { const decision = await aj.protect(req, { requested: 50 }); console.log("Arcjet decision", decision);
if (decision.isDenied()) { res.writeHead(429, { "Content-Type": "application/json" }); res.end( JSON.stringify({ error: "Too Many Requests", reason: decision.reason }), ); } else { res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ message: "Hello world" })); }});
server.listen(8000);import arcjet, { tokenBucket } from "@arcjet/node";import http from "node:http";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com characteristics: ["ip.src"], rules: [ tokenBucket({ mode: "LIVE", refillRate: 40_000, interval: "1d", capacity: 40_000, }), ],});
const server = http.createServer(async function ( req: http.IncomingMessage, res: http.ServerResponse,) { const decision = await aj.protect(req, { requested: 50 }); console.log("Arcjet decision", decision);
if (decision.isDenied()) { res.writeHead(429, { "Content-Type": "application/json" }); res.end( JSON.stringify({ error: "Too Many Requests", reason: decision.reason }), ); } else { res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ message: "Hello world" })); }});
server.listen(8000);import { ARCJET, type ArcjetNest, tokenBucket } from "@arcjet/nest";import { Controller, Get, HttpException, HttpStatus, Inject, Injectable, Req,} from "@nestjs/common";import type { Request } from "express";
// This would normally go in your service file e.g.// src/page/page.service.ts@Injectable()export class PageService { message(): { message: string } { return { message: "Hello world", }; }}
// This would normally go in your controller file e.g.// src/page/page.controller.ts@Controller("page")// Sets up the Arcjet protection without using a guard so we can access the// decision and use it in the controller.export class PageController { constructor( private readonly pageService: PageService, @Inject(ARCJET) private readonly arcjet: ArcjetNest, ) {}
@Get() async index(@Req() req: Request) { const decision = await this.arcjet .withRule( tokenBucket({ mode: "LIVE", refillRate: 40_000, interval: "1d", capacity: 40_000, }), ) .protect(req, { requested: 50 });
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new HttpException( "Too many requests", HttpStatus.TOO_MANY_REQUESTS, ); } else { throw new HttpException("Forbidden", HttpStatus.FORBIDDEN); } }
return this.pageService.message(); }}Rate limit headers
With a rate limit rule enabled, you can access additional metadata in every Arcjet decision result:
max(number): The configured maximum number of requests applied to this request.remaining(number): The number of requests remaining beforemaxis reached within the window.window(number): The total amount of seconds in which requests are counted.reset(number): The remaining amount of seconds in the window.
These can be used to return RateLimit HTTP headers (draft
RFC) to
offer the client more detail.
We provide the @arcjet/decorate
package for decorating
your responses with appropriate RateLimit headers based on a decision.
import { env } from "$env/dynamic/private";import { setRateLimitHeaders } from "@arcjet/decorate";import arcjet, { fixedWindow } from "@arcjet/sveltekit";import { error, json, type RequestEvent } from "@sveltejs/kit";
const aj = arcjet({ key: env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(event: RequestEvent) { const decision = await aj.protect(event);
if (decision.isDenied()) { return error(429, { message: "Too many requests" }); }
const headers = new Headers(); setRateLimitHeaders(headers, decision); return json({ message: "Hello world" }, { headers });}import { env } from "$env/dynamic/private";import { setRateLimitHeaders } from "@arcjet/decorate";import arcjet, { fixedWindow } from "@arcjet/sveltekit";import { error, json } from "@sveltejs/kit";
const aj = arcjet({ key: env.ARCJET_KEY, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(event) { const decision = await aj.protect(event);
if (decision.isDenied()) { return error(429, { message: "Too many requests" }); }
const headers = new Headers(); setRateLimitHeaders(headers, decision); return json({ message: "Hello world" }, { headers });}import arcjet, { fixedWindow } from "@arcjet/bun";import { setRateLimitHeaders } from "@arcjet/decorate";import { env } from "bun";
const aj = arcjet({ key: env.ARCJET_KEY, // Get your site key from https://app.arcjet.com // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
const ResponseWithRateLimit = (body, init, decision) => { const res = new Response(body, init); setRateLimitHeaders(res, decision); return res;};
export default { port: 3000, fetch: aj.handler(async (req) => { const decision = await aj.protect(req); console.log("Arcjet decision", decision);
if (decision.isDenied()) { return ResponseWithRateLimit( "Too many requests", { status: 429 }, decision, ); }
return ResponseWithRateLimit("Hello world", { status: 200 }, decision); }),};import arcjet, { fixedWindow, type ArcjetDecision } from "@arcjet/bun";import { setRateLimitHeaders } from "@arcjet/decorate";import { env } from "bun";
const aj = arcjet({ key: env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
const ResponseWithRateLimit = ( body: string, init: ResponseInit, decision: ArcjetDecision,) => { const res = new Response(body, init); setRateLimitHeaders(res, decision); return res;};
export default { port: 3000, fetch: aj.handler(async (req) => { const decision = await aj.protect(req); console.log("Arcjet decision", decision);
if (decision.isDenied()) { return ResponseWithRateLimit( "Too many requests", { status: 429 }, decision, ); }
return ResponseWithRateLimit("Hello world", { status: 200 }, decision); }),};import arcjet, { fixedWindow } from "@arcjet/node";import { setRateLimitHeaders } from "@arcjet/decorate";import http from "node:http";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Get your site key from https://app.arcjet.com // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
const server = http.createServer(async function (req, res) { const decision = await aj.protect(req); console.log("Arcjet decision", decision);
setRateLimitHeaders(res, decision);
if (decision.isDenied()) { res.writeHead(429, { "Content-Type": "application/json" }); res.end( JSON.stringify({ error: "Too Many Requests", reason: decision.reason }), ); } else { res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ message: "Hello world" })); }});
server.listen(8000);import arcjet, { fixedWindow } from "@arcjet/node";import { setRateLimitHeaders } from "@arcjet/decorate";import http from "node:http";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
const server = http.createServer(async function ( req: http.IncomingMessage, res: http.ServerResponse,) { const decision = await aj.protect(req); console.log("Arcjet decision", decision);
setRateLimitHeaders(res, decision);
if (decision.isDenied()) { res.writeHead(429, { "Content-Type": "application/json" }); res.end( JSON.stringify({ error: "Too Many Requests", reason: decision.reason }), ); } else { res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ message: "Hello world" })); }});
server.listen(8000);import arcjet, { fixedWindow } from "@arcjet/next";import { setRateLimitHeaders } from "@arcjet/decorate";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default async function handler(req, res) { const decision = await aj.protect(req);
setRateLimitHeaders(res, decision);
if (decision.isDenied()) { return res.status(429).json({ error: "Too Many Requests" }); }
res.status(200).json({ name: "Hello world" });}import arcjet, { fixedWindow } from "@arcjet/next";import { setRateLimitHeaders } from "@arcjet/decorate";import type { NextApiRequest, NextApiResponse } from "next";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default async function handler( req: NextApiRequest, res: NextApiResponse,) { const decision = await aj.protect(req);
setRateLimitHeaders(res, decision);
if (decision.isDenied()) { return res.status(429).json({ error: "Too Many Requests" }); }
res.status(200).json({ name: "Hello world" });}import arcjet, { fixedWindow } from "@arcjet/next";import { setRateLimitHeaders } from "@arcjet/decorate";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(req: Request) { const decision = await aj.protect(req);
const headers = new Headers();
setRateLimitHeaders(headers, decision);
if (decision.isDenied()) { return NextResponse.json( { error: "Too Many Requests", reason: decision.reason, }, { status: 429, headers }, ); }
return NextResponse.json( { message: "Hello world", }, { status: 200, headers }, );}import arcjet, { fixedWindow } from "@arcjet/next";import { setRateLimitHeaders } from "@arcjet/decorate";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(req) { const decision = await aj.protect(req);
const headers = new Headers();
setRateLimitHeaders(headers, decision);
if (decision.isDenied()) { return NextResponse.json( { error: "Too Many Requests", reason: decision.reason, }, { status: 429, headers }, ); }
return NextResponse.json( { message: "Hello world", }, { status: 200, headers }, );}import { setRateLimitHeaders } from "@arcjet/decorate";import arcjet, { fixedWindow } from "@arcjet/remix";import type { LoaderFunctionArgs } from "@remix-run/node";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function loader(args: LoaderFunctionArgs) { const decision = await aj.protect(args);
let headers: Record<string, string> = {}; setRateLimitHeaders(headers, decision);
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new Response("Too Many Requests", { status: 429, statusText: "Too Many Requests", headers, }); } else { throw new Response("Forbidden", { status: 403, statusText: "Forbidden", }); } }
return null;}import { setRateLimitHeaders } from "@arcjet/decorate";import arcjet, { fixedWindow } from "@arcjet/remix";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Get your site key from https://app.arcjet.com // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function loader(args) { const decision = await aj.protect(args);
let headers = {}; setRateLimitHeaders(headers, decision);
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new Response("Too Many Requests", { status: 429, statusText: "Too Many Requests", headers, }); } else { throw new Response("Forbidden", { status: 403, statusText: "Forbidden", }); } }
return null;}To set the rate limit headers on the NestJS response you need to add the
passthrough option to the @Res() decorator in your controller method i.e.
@Res({ passthrough: true }). See the NestJS docs on the library-specific
approach for
details.
import { setRateLimitHeaders } from "@arcjet/decorate";import { ARCJET, type ArcjetNest, fixedWindow } from "@arcjet/nest";import { Controller, Get, HttpException, HttpStatus, Inject, Injectable, Req, Res,} from "@nestjs/common";import type { Request } from "express";
// This would normally go in your service file e.g.// src/page/page.service.ts@Injectable()export class PageService { message(): { message: string } { return { message: "Hello world", }; }}
// This would normally go in your controller file e.g.// src/page/page.controller.ts@Controller("page")// Sets up the Arcjet protection without using a guard so we can access the// decision and use it in the controller.export class PageController { constructor( private readonly pageService: PageService, @Inject(ARCJET) private readonly arcjet: ArcjetNest, ) {}
@Get() // The passthrough option allows us to access the response object so we can // set the rate limit headers. See // https://docs.nestjs.com/controllers#library-specific-approach async index(@Req() req: Request, @Res({ passthrough: true }) res: Response) { const decision = await this.arcjet .withRule( fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ) .protect(req);
// Set the rate limit headers on the response object setRateLimitHeaders(res, decision);
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new HttpException( "Too many requests", HttpStatus.TOO_MANY_REQUESTS, ); } else { throw new HttpException("Forbidden", HttpStatus.FORBIDDEN); } }
return this.pageService.message(); }}This would result in draft RFC response headers similar to the following:
...< RateLimit: limit=10, remaining=5, reset=9< RateLimit-Policy: 10;w=10...Error handling
Arcjet is designed to fail open so that a service issue or misconfiguration does
not block all requests. The SDK will also time out and fail open after 1000ms
when NODE_ENV or ARCJET_ENV is development and 500ms otherwise. However,
in most cases, the response time will be less than 20-30ms.
If there is an error condition, Arcjet will return an ERROR conclusion.
import { env } from "$env/dynamic/private";import arcjet, { fixedWindow } from "@arcjet/sveltekit";import { error, json, type RequestEvent } from "@sveltejs/kit";
const aj = arcjet({ key: env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(event: RequestEvent) { const decision = await aj.protect(event);
if (decision.isErrored()) { // Fail open by logging the error and continuing console.warn("Arcjet error", decision.reason.message); // You could also fail closed here for very sensitive routes //return error(503, { message: "Service unavailable" }); }
if (decision.isDenied()) { return error(429, { message: "Too many requests" }); }
return json({ message: "Hello world" });}import { env } from "$env/dynamic/private";import arcjet, { fixedWindow } from "@arcjet/sveltekit";import { error, json } from "@sveltejs/kit";
const aj = arcjet({ key: env.ARCJET_KEY, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(event) { const decision = await aj.protect(event);
if (decision.isErrored()) { // Fail open by logging the error and continuing console.warn("Arcjet error", decision.reason.message); // You could also fail closed here for very sensitive routes //return error(503, { message: "Service unavailable" }); }
if (decision.isDenied()) { return error(429, { message: "Too many requests" }); }
return json({ message: "Hello world" });}import arcjet, { tokenBucket } from "@arcjet/bun";import { env } from "bun";
const aj = arcjet({ key: env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com characteristics: ["userId"], // track requests by a custom user ID rules: [ // Create a token bucket rate limit. Other algorithms are supported. tokenBucket({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only refillRate: 5, // refill 5 tokens per interval interval: 10, // refill every 10 seconds capacity: 10, // bucket maximum capacity of 10 tokens }), ],});
export default { port: 3000, fetch: aj.handler(async (req) => { const userId = "user123"; // Replace with your authenticated user ID const decision = await aj.protect(req, { userId, requested: 5 }); // Deduct 5 tokens from the bucket console.log("Arcjet decision", decision);
if (decision.isErrored()) { if (decision.reason.message.includes("missing User-Agent header")) { // Requests without User-Agent headers can not be identified as any // particular bot and will be marked as an errored decision. Most // legitimate clients always send this header, so we recommend blocking // requests without it. console.warn("User-Agent header is missing"); return new Response("Bad request", { status: 400 }); } else { // Fail open by logging the error and continuing console.warn("Arcjet error", decision.reason.message); // You could also fail closed here for very sensitive routes //return new Response("Service unavailable", { status: 503 }); } }
if (decision.isDenied()) { return new Response("Too many requests", { status: 429 }); }
return new Response("Hello world"); }),};import arcjet, { tokenBucket } from "@arcjet/bun";import { env } from "bun";
const aj = arcjet({ key: env.ARCJET_KEY, // Get your site key from https://app.arcjet.com characteristics: ["userId"], // track requests by a custom user ID rules: [ // Create a token bucket rate limit. Other algorithms are supported. tokenBucket({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only refillRate: 5, // refill 5 tokens per interval interval: 10, // refill every 10 seconds capacity: 10, // bucket maximum capacity of 10 tokens }), ],});
export default { port: 3000, fetch: aj.handler(async (req) => { const userId = "user123"; // Replace with your authenticated user ID const decision = await aj.protect(req, { userId, requested: 5 }); // Deduct 5 tokens from the bucket console.log("Arcjet decision", decision);
if (decision.isErrored()) { if (decision.reason.message.includes("missing User-Agent header")) { // Requests without User-Agent headers can not be identified as any // particular bot and will be marked as an errored decision. Most // legitimate clients always send this header, so we recommend blocking // requests without it. console.warn("User-Agent header is missing"); return new Response("Bad request", { status: 400 }); } else { // Fail open by logging the error and continuing console.warn("Arcjet error", decision.reason.message); // You could also fail closed here for very sensitive routes //return new Response("Service unavailable", { status: 503 }); } }
if (decision.isDenied()) { return new Response("Too many requests", { status: 429 }); }
return new Response("Hello world"); }),};import arcjet, { tokenBucket } from "@arcjet/remix";import type { LoaderFunctionArgs } from "@remix-run/node";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com characteristics: ["userId"], // track requests by a custom user ID rules: [ // Create a token bucket rate limit. Other algorithms are supported. tokenBucket({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only refillRate: 5, // refill 5 tokens per interval interval: 10, // refill every 10 seconds capacity: 10, // bucket maximum capacity of 10 tokens }), ],});
export async function loader(args: LoaderFunctionArgs) { const userId = "user123"; // Replace with your authenticated user ID const decision = await aj.protect(args, { userId, requested: 5 }); // Deduct 5 tokens from the bucket
if (decision.isErrored()) { if (decision.reason.message.includes("missing User-Agent header")) { // Requests without User-Agent headers can not be identified as any // particular bot and will be marked as an errored decision. Most // legitimate clients always send this header, so we recommend blocking // requests without it. console.warn("User-Agent header is missing"); throw new Response("Bad request", { status: 400, statusText: "Bad request", }); } else { // Fail open by logging the error and continuing console.warn("Arcjet error", decision.reason.message); // You could also fail closed here for very sensitive routes // throw new Response("Service unavailable", { status: 503, statusText: "Service unavailable" }); } }
if (decision.isDenied()) { throw new Response("Forbidden", { status: 403, statusText: "Forbidden" }); }
return null;}import arcjet, { tokenBucket } from "@arcjet/remix";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Get your site key from https://app.arcjet.com characteristics: ["userId"], // track requests by a custom user ID rules: [ // Create a token bucket rate limit. Other algorithms are supported. tokenBucket({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only refillRate: 5, // refill 5 tokens per interval interval: 10, // refill every 10 seconds capacity: 10, // bucket maximum capacity of 10 tokens }), ],});
export async function loader(args) { const userId = "user123"; // Replace with your authenticated user ID const decision = await aj.protect(args, { userId, requested: 5 }); // Deduct 5 tokens from the bucket
if (decision.isErrored()) { if (decision.reason.message.includes("missing User-Agent header")) { // Requests without User-Agent headers can not be identified as any // particular bot and will be marked as an errored decision. Most // legitimate clients always send this header, so we recommend blocking // requests without it. console.warn("User-Agent header is missing"); throw new Response("Bad request", { status: 400, statusText: "Bad request", }); } else { // Fail open by logging the error and continuing console.warn("Arcjet error", decision.reason.message); // You could also fail closed here for very sensitive routes // throw new Response("Service unavailable", { status: 503, statusText: "Service unavailable" }); } }
if (decision.isDenied()) { throw new Response("Forbidden", { status: 403, statusText: "Forbidden" }); }
return null;}import arcjet, { fixedWindow } from "@arcjet/next";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default async function handler(req, res) { const decision = await aj.protect(req);
if (decision.isErrored()) { if (decision.reason.message.includes("missing User-Agent header")) { // Requests without User-Agent headers can not be identified as any // particular bot and will be marked as an errored decision. Most // legitimate clients always send this header, so we recommend blocking // requests without it. console.warn("User-Agent header is missing"); return res.status(400).json({ error: "Bad request" }); } else { // Fail open by logging the error and continuing console.warn("Arcjet error", decision.reason.message); // You could also fail closed here for very sensitive routes //return res.status(503).json({ error: "Service unavailable" }); } }
if (decision.isDenied()) { return res.status(429).json({ error: "Too Many Requests" }); }
res.status(200).json({ name: "Hello world" });}import arcjet, { fixedWindow } from "@arcjet/next";import type { NextApiRequest, NextApiResponse } from "next";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default async function handler( req: NextApiRequest, res: NextApiResponse,) { const decision = await aj.protect(req);
if (decision.isErrored()) { if (decision.reason.message.includes("missing User-Agent header")) { // Requests without User-Agent headers can not be identified as any // particular bot and will be marked as an errored decision. Most // legitimate clients always send this header, so we recommend blocking // requests without it. console.warn("User-Agent header is missing"); return res.status(400).json({ error: "Bad request" }); } else { // Fail open by logging the error and continuing console.warn("Arcjet error", decision.reason.message); // You could also fail closed here for very sensitive routes //return res.status(503).json({ error: "Service unavailable" }); } }
if (decision.isDenied()) { return res.status(429).json({ error: "Too Many Requests" }); }
res.status(200).json({ name: "Hello world" });}import arcjet, { fixedWindow } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(req: Request) { const decision = await aj.protect(req);
if (decision.isErrored()) { if (decision.reason.message.includes("missing User-Agent header")) { // Requests without User-Agent headers can not be identified as any // particular bot and will be marked as an errored decision. Most // legitimate clients always send this header, so we recommend blocking // requests without it. console.warn("User-Agent header is missing"); return NextResponse.json({ error: "Bad request" }, { status: 400 }); } else { // Fail open by logging the error and continuing console.warn("Arcjet error", decision.reason.message); // You could also fail closed here for very sensitive routes //return NextResponse.json({ error: "Service unavailable" }, { status: 503 }); } }
if (decision.isDenied()) { return NextResponse.json( { error: "Too Many Requests", reason: decision.reason, }, { status: 429, }, ); }
return NextResponse.json({ message: "Hello world", });}import arcjet, { fixedWindow } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(req) { const decision = await aj.protect(req);
if (decision.isErrored()) { if (decision.reason.message.includes("missing User-Agent header")) { // Requests without User-Agent headers can not be identified as any // particular bot and will be marked as an errored decision. Most // legitimate clients always send this header, so we recommend blocking // requests without it. console.warn("User-Agent header is missing"); return NextResponse.json({ error: "Bad request" }, { status: 400 }); } else { // Fail open by logging the error and continuing console.warn("Arcjet error", decision.reason.message); // You could also fail closed here for very sensitive routes //return NextResponse.json({ error: "Service unavailable" }, { status: 503 }); } }
if (decision.isDenied()) { return NextResponse.json( { error: "Too Many Requests", reason: decision.reason, }, { status: 429, }, ); }
return NextResponse.json({ message: "Hello world", });}import arcjet, { tokenBucket } from "@arcjet/node";import http from "node:http";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Get your site key from https://app.arcjet.com characteristics: ["userId"], // track requests by a custom user ID rules: [ // Create a token bucket rate limit. Other algorithms are supported. tokenBucket({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only refillRate: 5, // refill 5 tokens per interval interval: 10, // refill every 10 seconds capacity: 10, // bucket maximum capacity of 10 tokens }), ],});
const server = http.createServer(async function (req, res) { const userId = "user123"; // Replace with your authenticated user ID const decision = await aj.protect(req, { userId, requested: 5 }); // Deduct 5 tokens from the bucket console.log("Arcjet decision", decision);
if (decision.isErrored()) { if (decision.reason.message.includes("missing User-Agent header")) { // Requests without User-Agent headers can not be identified as any // particular bot and will be marked as an errored decision. Most // legitimate clients always send this header, so we recommend blocking // requests without it. console.warn("User-Agent header is missing"); res.writeHead(400, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "Bad request" })); } else { // Fail open by logging the error and continuing console.warn("Arcjet error", decision.reason.message); // You could also fail closed here for very sensitive routes //res.writeHead(503, { "Content-Type": "application/json" }); //res.end(JSON.stringify({ error: "Service unavailable" })); } }
if (decision.isDenied()) { res.writeHead(429, { "Content-Type": "application/json" }); res.end( JSON.stringify({ error: "Too Many Requests", reason: decision.reason }), ); } else { res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ message: "Hello world" })); }});
server.listen(8000);import arcjet, { tokenBucket } from "@arcjet/node";import http from "node:http";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com characteristics: ["userId"], // track requests by a custom user ID rules: [ // Create a token bucket rate limit. Other algorithms are supported. tokenBucket({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only refillRate: 5, // refill 5 tokens per interval interval: 10, // refill every 10 seconds capacity: 10, // bucket maximum capacity of 10 tokens }), ],});
const server = http.createServer(async function ( req: http.IncomingMessage, res: http.ServerResponse,) { const userId = "user123"; // Replace with your authenticated user ID const decision = await aj.protect(req, { userId, requested: 5 }); // Deduct 5 tokens from the bucket console.log("Arcjet decision", decision);
if (decision.isErrored()) { if (decision.reason.message.includes("missing User-Agent header")) { // Requests without User-Agent headers can not be identified as any // particular bot and will be marked as an errored decision. Most // legitimate clients always send this header, so we recommend blocking // requests without it. console.warn("User-Agent header is missing"); res.writeHead(400, { "Content-Type": "application/json" }); res.end(JSON.stringify({ error: "Bad request" })); } else { // Fail open by logging the error and continuing console.warn("Arcjet error", decision.reason.message); // You could also fail closed here for very sensitive routes //res.writeHead(503, { "Content-Type": "application/json" }); //res.end(JSON.stringify({ error: "Service unavailable" })); } }
if (decision.isDenied()) { res.writeHead(429, { "Content-Type": "application/json" }); res.end( JSON.stringify({ error: "Too Many Requests", reason: decision.reason }), ); } else { res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ message: "Hello world" })); }});
server.listen(8000);import { ARCJET, type ArcjetNest, fixedWindow } from "@arcjet/nest";import { Controller, Get, HttpException, HttpStatus, Inject, Injectable, Logger, Req, Res,} from "@nestjs/common";import type { Request } from "express";
// This would normally go in your service file e.g.// src/page/page.service.ts@Injectable()export class PageService { message(): { message: string } { return { message: "Hello world", }; }}
// This would normally go in your controller file e.g.// src/page/page.controller.ts@Controller("page")// Sets up the Arcjet protection without using a guard so we can access the// decision and use it in the controller.export class PageController { // Make use of the NestJS logger: https://docs.nestjs.com/techniques/logger // See // https://github.com/arcjet/example-nestjs/blob/ec742e58c8da52d0a399327182c79e3f4edc8f3b/src/app.module.ts#L29 // and https://github.com/arcjet/example-nestjs/blob/main/src/arcjet-logger.ts // for an example of how to connect Arcjet to the NestJS logger private readonly logger = new Logger(PageController.name);
constructor( private readonly pageService: PageService, @Inject(ARCJET) private readonly arcjet: ArcjetNest, ) {}
@Get() async index(@Req() req: Request) { const decision = await this.arcjet .withRule( fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ) .protect(req);
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { throw new HttpException( "Too many requests", HttpStatus.TOO_MANY_REQUESTS, ); } else { throw new HttpException("Forbidden", HttpStatus.FORBIDDEN); } } else if (decision.isErrored()) { if (decision.reason.message.includes("missing User-Agent header")) { // Requests without User-Agent headers can not be identified as any // particular bot and will be marked as an errored decision. Most // legitimate clients always send this header, so we recommend blocking // requests without it. this.logger.warn("User-Agent header is missing"); throw new HttpException("Bad request", HttpStatus.BAD_REQUEST); } else { // Fail open to prevent an Arcjet error from blocking all requests. You // may want to fail closed if this controller is very sensitive this.logger.error(`Arcjet error: ${decision.reason.message}`); } }
return this.pageService.message(); }}Testing
Arcjet runs the same in any environment, including locally and in CI. You can
use the mode set to DRY_RUN to log the results of rule execution without
blocking any requests.
We have an example test framework you can use to automatically test your rules. Arcjet can also be triggered based using a sample of your traffic.
See the Testing section of the docs for details.
Examples
Rate limit by IP address
The example below shows how to configure a rate limit on a single API route. It applies a limit of 60 requests per hour per IP address. If the limit is exceeded, the client is blocked for 10 minutes before being able to make any further requests.
Applying a rate limit by IP address is the default if no
characteristics are specified.
import arcjet, { fixedWindow } from "@arcjet/next";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Tracking by ip.src is the default if not specified // characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default async function handler(req, res) { const decision = await aj.protect(req);
if (decision.isDenied()) { return res.status(429).json({ error: "Too Many Requests" }); }
res.status(200).json({ name: "Hello world" });}import arcjet, { fixedWindow } from "@arcjet/next";import type { NextApiRequest, NextApiResponse } from "next";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified // characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default async function handler( req: NextApiRequest, res: NextApiResponse,) { const decision = await aj.protect(req);
if (decision.isDenied()) { return res.status(429).json({ error: "Too Many Requests" }); }
res.status(200).json({ name: "Hello world" });}import arcjet, { fixedWindow } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified // characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(req: Request) { const decision = await aj.protect(req);
if (decision.isDenied()) { return NextResponse.json( { error: "Too Many Requests", reason: decision.reason, }, { status: 429, }, ); }
return NextResponse.json({ message: "Hello world", });}import arcjet, { fixedWindow } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Tracking by ip.src is the default if not specified // characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(req) { const decision = await aj.protect(req);
if (decision.isDenied()) { return NextResponse.json( { error: "Too Many Requests", reason: decision.reason, }, { status: 429, }, ); }
return NextResponse.json({ message: "Hello world", });}Rate limit by IP address with custom response
The example below is the same as the one above. However this example also shows a customized response rather than the default.
import arcjet, { fixedWindow } from "@arcjet/next";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Tracking by ip.src is the default if not specified // characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default async function handler(req, res) { const decision = await aj.protect(req);
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { return res.status(429).json({ error: "Too Many Requests" }); } else { return res .status(403) .json({ error: "Forbidden", reason: decision.reason }); } }
res.status(200).json({ name: "Hello world" });}import arcjet, { fixedWindow } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified // characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(req: Request) { const decision = await aj.protect(req);
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { return NextResponse.json({ error: "Too Many Requests" }, { status: 429 }); } else { return NextResponse.json( { error: "Forbidden", reason: decision.reason }, { status: 403 }, ); } }
return NextResponse.json({ message: "Hello world", });}import arcjet, { fixedWindow } from "@arcjet/next";import type { NextApiRequest, NextApiResponse } from "next";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified // characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default async function handler( req: NextApiRequest, res: NextApiResponse,) { const decision = await aj.protect(req);
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { return res.status(429).json({ error: "Too Many Requests" }); } else { return res .status(403) .json({ error: "Forbidden", reason: decision.reason }); } }
res.status(200).json({ name: "Hello world" });}import arcjet, { fixedWindow } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Tracking by ip.src is the default if not specified // characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function GET(req) { const decision = await aj.protect(req);
if (decision.isDenied()) { if (decision.reason.isRateLimit()) { return res.status(429).json({ error: "Too Many Requests" }); } else { return res .status(403) .json({ error: "Forbidden", reason: decision.reason }); } }
return NextResponse.json({ message: "Hello world", });}Rate limit by AI tokens
If you are building an AI application you may be more interested in the number of AI tokens rather than the number of HTTP requests. Popular AI APIs such as OpenAI are billed based on the number of tokens consumed and the number of tokens is variable depending on the request e.g. conversation length or image size.
The token bucket algorithm is a good fit for this use case because you can vary the number of tokens withdrawn from the bucket with every request.
The example below configures a token bucket rate limit using the
openai-chat-tokens library to
track the number of tokens used by a gpt-3.5-turbo AI chatbot. It sets a limit
of 2,000 tokens per hour with a maximum of 5,000 tokens in the bucket. This
allows for a reasonable conversation length without consuming too many tokens.
See the arcjet-js GitHub repo for a full example using Next.js.
The Next.js pages router does not support streaming responses so you should
use the app router for this example. You can still use the pages/
directory for the rest of your application. See the Next.js AI docs for
details.
The Next.js pages router does not support streaming responses so you should
use the app router for this example. You can still use the pages/
directory for the rest of your application. See the Next.js AI docs for
details.
// This example is adapted from https://sdk.vercel.ai/docs/guides/frameworks/nextjs-appimport { openai } from "@ai-sdk/openai";import arcjet, { shield, tokenBucket } from "@arcjet/next";import { streamText } from "ai";import { promptTokensEstimate } from "openai-chat-tokens";
const aj = arcjet({ // Get your site key from https://app.arcjet.com // and set it as an environment variable rather than hard coding. // See: https://nextjs.org/docs/app/building-your-application/configuring/environment-variables key: process.env.AJ_KEY!, characteristics: ["ip.src"], // track requests by IP address rules: [ tokenBucket({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only refillRate: 2_000, interval: "1h", capacity: 5_000, }), ],});
// Allow streaming responses up to 30 secondsexport const maxDuration = 30;
// Edge runtime allows for streaming responsesexport const runtime = "edge";
export async function POST(req: Request) { const { messages } = await req.json();
// Estimate the number of tokens required to process the request const estimate = promptTokensEstimate({ messages, });
console.log("Token estimate", estimate);
// Withdraw tokens from the token bucket const decision = await aj.protect(req, { requested: estimate }); console.log("Arcjet decision", decision.conclusion);
if (decision.reason.isRateLimit()) { console.log("Requests remaining", decision.reason.remaining); }
// If the request is denied, return a 429 if (decision.isDenied()) { if (decision.reason.isRateLimit()) { return new Response("Too Many Requests", { status: 429, }); } else { return new Response("Forbidden", { status: 403, }); } }
// If the request is allowed, continue to use OpenAI const result = await streamText({ model: openai("gpt-4-turbo"), messages, });
return result.toDataStreamResponse();}// This example is adapted from https://sdk.vercel.ai/docs/guides/frameworks/nextjs-appimport { openai } from "@ai-sdk/openai";import arcjet, { shield, tokenBucket } from "@arcjet/next";import { streamText } from "ai";import { promptTokensEstimate } from "openai-chat-tokens";
const aj = arcjet({ // Get your site key from https://app.arcjet.com // and set it as an environment variable rather than hard coding. // See: https://nextjs.org/docs/app/building-your-application/configuring/environment-variables key: process.env.AJ_KEY, characteristics: ["ip.src"], // track requests by IP address rules: [ tokenBucket({ mode: "LIVE", // will block requests. Use "DRY_RUN" to log only refillRate: 2_000, interval: "1h", capacity: 5_000, }), ],});
// Allow streaming responses up to 30 secondsexport const maxDuration = 30;
// Edge runtime allows for streaming responsesexport const runtime = "edge";
export async function POST(req) { const { messages } = await req.json();
// Estimate the number of tokens required to process the request const estimate = promptTokensEstimate({ messages, });
console.log("Token estimate", estimate);
// Withdraw tokens from the token bucket const decision = await aj.protect(req, { requested: estimate }); console.log("Arcjet decision", decision.conclusion);
if (decision.reason.isRateLimit()) { console.log("Requests remaining", decision.reason.remaining); }
// If the request is denied, return a 429 if (decision.isDenied()) { if (decision.reason.isRateLimit()) { return new Response("Too Many Requests", { status: 429, }); } else { return new Response("Forbidden", { status: 403, }); } }
// If the request is allowed, continue to use OpenAI const result = await streamText({ model: openai("gpt-4-turbo"), messages, });
return result.toDataStreamResponse();}Rate limit by API key header
APIs are commonly protected by keys. You may wish to apply a rate limit based on the key, regardless of which IPs the requests come from. To achieve this, you can specify the characteristics Arcjet will use to track the limit.
The example below shows how to configure a rate limit on a single API route. It
applies a limit of 60 requests per hour per API key, where the key is provided
in a custom header called x-api-key. If the limit is exceeded, the client is
blocked for 10 minutes before being able to make any further requests.
import arcjet, { fixedWindow } from "@arcjet/next";
const aj = arcjet({ key: process.env.ARCJET_KEY!, characteristics: ['http.request.headers["x-api-key"]'], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});Global rate limit
Using Next.js middleware allows you to set a rate limit that applies to every route:
import arcjet, { createMiddleware, fixedWindow } from "@arcjet/next";export const config = { // matcher tells Next.js which routes to run the middleware on. // This runs the middleware on all routes except for static assets. matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],};const aj = arcjet({ key: process.env.ARCJET_KEY!, rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});// Pass any existing middleware with the optional existingMiddleware propexport default createMiddleware(aj);Response based on the path
You can also use the req
NextRequest
object to customize the response based on the path. In this example, we’ll
return a JSON response for API requests, and a HTML response for other requests.
import arcjet, { fixedWindow } from "@arcjet/next";import { NextRequest, NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function middleware(req: NextRequest, res: NextResponse) { const decision = await aj.protect(req);
if (decision.isDenied()) { // If this is an API request, return a JSON response if (req.nextUrl.pathname.startsWith("/api")) { return new NextResponse(JSON.stringify({ error: "Too many requests" }), { status: 429, headers: { "content-type": "application/json" }, }); } else { return new NextResponse("Too many requests", { status: 429, headers: { "content-type": "text/html" }, }); } }}Rewrite or redirect
The
NextResponse
object returned to the client can also be used to rewrite or redirect the
request. For example, you might want to return a JSON response for API route
requests, but redirect all page route requests to an error page.
import arcjet, { fixedWindow } from "@arcjet/next";import { NextRequest, NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export async function middleware(req: NextRequest, res: NextResponse) { const decision = await aj.protect(req);
if (decision.isDenied()) { // If this is an API request, return a JSON response if (req.nextUrl.pathname.startsWith("/api")) { return new NextResponse(JSON.stringify({ error: "Too many requests" }), { status: 429, headers: { "content-type": "application/json" }, }); } else { return NextResponse.redirect("/rate-limited"); } }}Wrap existing handler
All the examples on this page show how you can inspect the decision to control
what to do next. However, if you just wish to send a generic 429 Too Many Requests response you can delegate this to Arcjet by wrapping your handler
withArcjet.
For both the Node or Edge runtime:
import arcjet, { fixedWindow, withArcjet } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export const GET = withArcjet(aj, async (req: Request) => { return NextResponse.json({ message: "Hello world", });});or both the Node or Edge runtime:
import arcjet, { fixedWindow, withArcjet } from "@arcjet/next";import { NextResponse } from "next/server";
const aj = arcjet({ key: process.env.ARCJET_KEY, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export const GET = withArcjet(aj, async (req) => { return NextResponse.json({ message: "Hello world", });});For the Node (default) runtime:
import arcjet, { fixedWindow, withArcjet } from "@arcjet/next";import type { NextApiRequest, NextApiResponse } from "next";
export const config = { runtime: "edge",};
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default withArcjet( aj, async (req: NextApiRequest, res: NextApiResponse) => { res.status(200).json({ name: "Hello world" }); },);For the Edge runtime:
import arcjet, { fixedWindow, withArcjet } from "@arcjet/next";import { NextRequest, NextResponse } from "next/server";
export const config = { runtime: "edge",};
const aj = arcjet({ key: process.env.ARCJET_KEY!, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default withArcjet(aj, async (req: NextRequest) => { return NextResponse.json({ message: "Hello world", });});For the Node (default) runtime:
import arcjet, { fixedWindow, withArcjet } from "@arcjet/next";
export const config = { runtime: "edge",};
const aj = arcjet({ key: process.env.ARCJET_KEY, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default withArcjet(aj, async (req, res) => { res.status(200).json({ name: "Hello world" });});For the Edge runtime:
import arcjet, { fixedWindow, withArcjet } from "@arcjet/next";import { NextRequest, NextResponse } from "next/server";
export const config = { runtime: "edge",};
const aj = arcjet({ key: process.env.ARCJET_KEY, // Tracking by ip.src is the default if not specified //characteristics: ["ip.src"], rules: [ fixedWindow({ mode: "LIVE", window: "1h", max: 60, }), ],});
export default withArcjet(aj, async (req) => { return NextResponse.json({ message: "Hello world", });});