@fastify/rate-limit

To use the plugin, register it with your Fastify instance. By default, it adds an onRequest hook that checks the client's IP address against a configured timeWindow and max request limit. If the limit is exceeded, the client receives a 429 Too Many Requests response.

import Fastify from 'fastify'

const fastify = Fastify()
await fastify.register(import('@fastify/rate-limit'), {
  max: 100,
  timeWindow: '1 minute'
})

fastify.get('/', (request, reply) => {
  reply.send({ hello: 'world' })
})

fastify.listen({ port: 3000 }, err => {
  if (err) throw err
  console.log('Server listening at http://localhost:3000')
})

When a client hits the rate limit, you can customize the response in two ways:

1. Using errorResponseBuilder: Provide a function during plugin registration to return a custom object.
2. Using a custom error handler: Use Fastify's setErrorHandler to intercept the 429 status code and modify the response.

Default error response structure:

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded, retry in 1 minute"
}

await fastify.register(import('@fastify/rate-limit'), {
  errorResponseBuilder: function (request, context) {
    return {
      statusCode: 429,
      error: 'Too Many Requests',
      message: `I only allow ${context.max} requests per ${context.after} to this Website. Try again soon.`,
      date: Date.now(),
      expiresIn: context.ttl // milliseconds
    }
  }
})

You can override global plugin settings for specific routes using the config.rateLimit object in the route definition.

• To disable rate limiting on a route that has global limiting enabled, set rateLimit: false.
• To override settings, provide a rateLimit object with specific max, timeWindow, groupId, etc.
• Use groupId to group multiple routes together for a shared per-group rate limit.

// Disable rate limiting for a specific route
fastify.get('/public', {
  config: {
    rateLimit: false
  }
}, (request, reply) => {
  reply.send({ hello: 'no limits here' }})
})

// Override settings and use a groupId
fastify.get('/otp/send', {
  config: {
    rateLimit: {
      max: 3,
      timeWindow: '1 minute',
      groupId: 'OTP'
    }
  }
}, (request, reply) => {
  reply.send({ hello: 'grouped limit' }})
})

Install the @fastify/rate-limit plugin using npm to add rate limiting capabilities to your Fastify application.

npm i @fastify/rate-limit

To prevent attackers from brute-forcing URLs via 404 errors, you can apply rate limiting to your Not Found handler. You can use the plugin's preHandler capability within setNotFoundHandler.

const fastify = Fastify()
await fastify.register(rateLimit, { global: true, max: 2, timeWindow: 1000 })

fastify.setNotFoundHandler({
  preHandler: fastify.rateLimit({
    max: 4,
    timeWindow: 500
  })
}, function (request, reply) {
  reply.code(404).send({ hello: 'world' })
})

The plugin supports different storage backends to track request counts:

1. LocalStore (Default): Uses in-memory storage. Best for single-instance applications.
2. RedisStore: Uses Redis for distributed rate limiting across multiple server instances. To use this, provide a redis connection object in the plugin settings.
3. Custom Store: You can provide your own store implementation via the store option. A custom store must implement an incr(key, callback, timeWindow, max) method. If using { increment: false } in manual calls, the store must also implement a read(key, callback, timeWindow, max) method.

// Example using Redis
fastify.register(rateLimit, {
  redis: new Redis({ host: '127.0.0.1' }),
  nameSpace: 'my-app-ratelimit'
})

You can override global settings by adding a rateLimit object to the config property of a route definition. This allows for granular control (e.g., stricter limits on sensitive endpoints like /login).

Supported configuration keys in routeOptions.config.rateLimit include all global options mentioned in the registration settings, plus groupId (a string used to append to the rate limit key to create separate buckets for the same IP/user).

To disable rate limiting for a specific route, set rateLimit: false in the route config.

fastify.get('/sensitive', {
  config: {
    rateLimit: {
      max: 5,
      timeWindow: '1 minute',
      groupId: 'login-attempts'
    }
  }
}, async (request, reply) => {
  return { status: 'ok' }
})

To use rate limiting in your Fastify application, register the @fastify/rate-limit plugin. You can provide global configuration settings during registration that will apply to all routes unless overridden by specific route configurations.

const fastify = require('fastify')()
const rateLimit = require('@fastify/rate-limit')

fastify.register(rateLimit, {
  max: 1000,
  timeWindow: '1 minute'
})

The plugin adds headers to the response to inform the client about their current status.

Standard Headers (Default):

• x-ratelimit-limit: Total requests allowed in the window.
• x-ratelimit-remaining: Requests remaining in the current window.
• x-ratelimit-reset: Seconds remaining until the limit resets.
• retry-after: (Only when limit is reached) Seconds to wait before retrying.

IETF Draft Spec Headers (if enableDraftSpec: true):

• ratelimit-limit
• ratelimit-remaining
• ratelimit-reset
• retry-after