Merge pull request #124 from kevcomparadise/feat/per-route-rate-limiting

(feat) Per-Route Rate Limiting

Author: rrd108

README.md

@@ -258,6 +258,49 @@ export default defineTask({
 ```
 Make sure to configure `ipTTL` in your `nuxt.config.ts` under `nuxtApiShield` if you wish to use a value different from the default (7 days). Setting `ipTTL: 0` (or any non-positive number) in your config will disable this cleanup task. The `RateLimit` type should be available via `#imports` if your module exports it or makes it available to Nuxt's auto-import system.
 
+## Per-Route Rate Limiting
+
+`nuxt-api-shield` supports **per-route rate limiting**, allowing you to define custom limits for specific API endpoints while keeping a global default configuration for all other routes.
+
+This is useful when certain endpoints (such as `/api/login`, `/api/auth`, or `/api/payment`) require stricter protection.
+
+---
+
+### Configuration Example
+
+The `routes` option accepts a mixed array:
+
+- **String:** applies the **global rate limit configuration**
+- **Object:** applies **custom per-route limits**
+
+```ts
+export default defineNuxtConfig({
+  modules: ['nuxt-api-shield'],
+
+  nuxtApiShield: {
+    limit: {
+      max: 12,
+      duration: 108,
+      ban: 3600
+    },
+
+    routes: [
+      // 1. String: uses the global default limit
+      '/api/example',
+
+      // 2. Object: custom rate limit for a specific route
+      {
+        path: '/api/example-per-route',
+        max: 5,       // custom max requests
+        duration: 10  // custom duration (seconds)
+        // ⚠️ "ban" always uses the global value
+      }
+    ],
+  }
+})
+```
+
+
 ## Important Considerations
 
 ### Data Privacy (IP Address Storage)

playground/nuxt.config.ts

@@ -23,6 +23,14 @@ export default defineNuxtConfig({
       duration: 10,
       ban: 30,
     },
+    routes: [
+      '/api/example',
+      {
+        path: '/api/example-per-route',
+        max: 5,
+        duration: 10,
+      },
+    ],
     delayOnBan: true,
     retryAfterHeader: true,
     log: {

playground/server/api/example-per-route.get.ts

@@ -0,0 +1,3 @@
+export default defineEventHandler(async () => {
+  return { result: 'Hello World !' }
+})

src/module.ts

@@ -6,20 +6,7 @@ import {
   addServerImports,
 } from '@nuxt/kit'
 import defu from 'defu'
-import type { LogEntry } from './runtime/server/types/LogEntry'
-
-export interface ModuleOptions {
-  limit: {
-    max: number
-    duration: number
-    ban: number
-  }
-  delayOnBan: boolean
-  errorMessage: string
-  retryAfterHeader: boolean
-  log?: LogEntry
-  routes: string[]
-}
+import type { ModuleOptions } from './type'
 
 export default defineNuxtModule<ModuleOptions>({
   meta: {

src/runtime/server/middleware/shield.ts

@@ -8,18 +8,35 @@ import {
   useStorage,
 } from '#imports'
 import type { RateLimit } from '../types/RateLimit'
+import type { ModuleOptions } from '~/src/type'
+import {
+  extractRoutePaths,
+  getRouteLimit,
+  hasRouteLimit,
+} from '../utils/routes'
+import createKey from '../utils/createKey'
 
 export default defineEventHandler(async (event) => {
-  const config = useRuntimeConfig().public.nuxtApiShield
+  const config = useRuntimeConfig().public.nuxtApiShield as ModuleOptions
   const url = getRequestURL(event)
+
+  /**
+   * Get Route limit, if match with configured route its override default limit configuration
+   */
+  const routeLimit = getRouteLimit(url?.pathname, config)
+  const isRouteLimit = hasRouteLimit(url?.pathname, config)
+  const routePaths = extractRoutePaths(config.routes || [])
   if (!url?.pathname?.startsWith('/api/')
-    || (config.routes?.length && !config.routes.some(route => url.pathname?.startsWith(route)))) {
+    || (routePaths.length && !routePaths.some(path => url.pathname.startsWith(path)))) {
     return
   }
 
   const shieldStorage = useStorage('shield')
   const requestIP = getRequestIP(event, { xForwardedFor: true }) || 'unKnownIP'
-  const banKey = `ban:${requestIP}`
+  const banKey = createKey({
+    ipAddress: requestIP,
+    prefix: 'ban',
+  })
   const bannedUntilRaw = await shieldStorage.getItem(banKey)
   const bannedUntil = typeof bannedUntilRaw === 'number' ? bannedUntilRaw : Number(bannedUntilRaw)
 
@@ -39,12 +56,16 @@ export default defineEventHandler(async (event) => {
     await shieldStorage.removeItem(banKey)
   }
 
-  const ipKey = `ip:${requestIP}`
+  const ipKey = createKey({
+    ipAddress: requestIP,
+    path: isRouteLimit ? url?.pathname : undefined,
+  })
+
   const req = await shieldStorage.getItem(ipKey) as RateLimit
   const now = Date.now()
 
   // Check if a new request is outside the duration window
-  if (!req || (now - req.time) / 1000 >= config.limit.duration) {
+  if (!req || (now - req.time) / 1000 >= routeLimit.duration) {
     // If no record exists, or the duration has expired, reset the counter and timestamp
     await shieldStorage.setItem(ipKey, {
       count: 1,
@@ -58,15 +79,15 @@ export default defineEventHandler(async (event) => {
   shieldLog(req, requestIP, url.toString())
 
   // Check if the new count triggers a rate limit
-  if (req.count > config.limit.max) {
-    const banUntil = now + config.limit.ban * 1e3
+  if (req.count > routeLimit.max) {
+    const banUntil = now + routeLimit.ban * 1e3
     await shieldStorage.setItem(banKey, banUntil)
     await shieldStorage.setItem(ipKey, {
       count: 1,
       time: now,
     })
     if (config.retryAfterHeader) {
-      event.node.res.setHeader('Retry-After', config.limit.ban)
+      event.node.res.setHeader('Retry-After', routeLimit.ban)
     }
     throw createError({
       statusCode: 429,

src/runtime/server/utils/createKey.ts

@@ -0,0 +1,25 @@
+type CreateKeyArgs = {
+  ipAddress: string
+  prefix?: string
+  path?: string
+}
+
+/**
+ * Builds a namespaced storage key for rate-limiting operations.
+ *
+ * @param options - Object containing key generation parameters.
+ * @returns A formatted storage key string.
+ */
+const createKey = (options: CreateKeyArgs) => {
+  const args = Object.assign({}, {
+    prefix: 'ip',
+  }, options)
+
+  if (args.path) {
+    return `${args.prefix}:${args.path}:${args.ipAddress}`
+  }
+
+  return `${args.prefix}:${args.ipAddress}`
+}
+
+export default createKey

src/runtime/server/utils/routes.ts

@@ -0,0 +1,39 @@
+import type { LimitConfiguration, ModuleOptions } from '~/src/type'
+
+/**
+ * Extract from config route path
+ * @param routes contains array of route configuration
+ */
+export function extractRoutePaths(routes: Array<string | { path: string }>): string[] {
+  return routes.map((route) => {
+    if (typeof route === 'string') {
+      return route
+    }
+    return route.path
+  })
+}
+
+/**
+ * This function merges the global `limit` configuration with the per-route
+ *
+ * @param path - pathname from event
+ * @param config - The module configuration containing global and per-route settings.
+ * @returns The merged rate limit configuration for the route.
+ */
+export function getRouteLimit(path: string, config: ModuleOptions): LimitConfiguration {
+  return Object.assign({}, config.limit, config.routes?.find(route =>
+    typeof route !== 'string' && route.path === path,
+  ) ?? {})
+}
+
+/**
+ * Checks route path has a custom per-route limit defined.
+ * @param path - pathname to check.
+ * @param config - The module configuration containing route definitions.
+ * @returns True if a matching custom route limit exists, false otherwise.
+ */
+export function hasRouteLimit(path: string, config: ModuleOptions): boolean {
+  return config.routes?.find(route =>
+    typeof route !== 'string' && route.path === path,
+  ) !== undefined
+}

src/type.d.ts

@@ -0,0 +1,20 @@
+import type { LogEntry } from './runtime/server/types/LogEntry'
+
+export interface LimitConfiguration {
+  max: number
+  duration: number
+  ban: number
+}
+
+export interface RouteLimitConfiguration extends Partial<LimitConfiguration> {
+  path: string
+}
+
+export interface ModuleOptions {
+  limit: LimitConfiguration
+  delayOnBan: boolean
+  errorMessage: string
+  retryAfterHeader: boolean
+  log?: LogEntry
+  routes: Array<string | RouteLimitConfiguration>
+}

test/fixtures/withPerRouteLimit/app.vue

@@ -0,0 +1,5 @@
+<template>
+  <div>withPerRouteLimit</div>
+</template>
+
+<script setup></script>

test/fixtures/withPerRouteLimit/nuxt.config.ts

@@ -0,0 +1,33 @@
+import nuxtApiShield from '../../../src/module'
+
+export default defineNuxtConfig({
+  modules: [nuxtApiShield],
+  nitro: {
+    storage: {
+      shield: {
+        // driver: "memory",
+        driver: 'fs',
+        base: '_testWithRoutesLimiteShield',
+      },
+    },
+  },
+  nuxtApiShield: {
+    limit: {
+      max: 2,
+      duration: 3,
+      ban: 10,
+    },
+    errorMessage: 'Wait ! Something went wrong',
+    retryAfterHeader: true,
+    log: { path: '', attempts: 0 },
+    routes: [
+      '/api/example',
+      {
+        path: '/api/example-specific-limit',
+        max: 1,
+        duration: 2,
+        ban: 50,
+      },
+    ],
+  },
+})