@lock-sdk/rate-limit NPM

Rate Limit

A powerful and flexible rate limiting module for the Lock security framework. Protect your backend services from abuse, brute-force attacks, DDoS attempts, and unexpected surges in traffic using a variety of strategies and pluggable storage options.

🚀 Features

✅ Fixed, sliding, token, and leaky bucket strategies
🌍 Country-based throttling via IP geolocation
🌐 Distributed rate limit storage with Redis & Upstash support
🛡️ Built-in DDoS heuristics and adaptive escalation
🧠 Custom key generators and smart skip logic
📦 Headers for standard and RFC-compliant rate info
🔥 Fast in-memory caching via LRU strategies

🛠 Usage

Basic Example (100 requests per minute)

import { secure, rateLimit } from '@lock-sdk/main';

const middleware = secure()(
  rateLimit({
    limit: 100,
    windowMs: 60_000, // 1 minute
  })
);

⚙️ Configuration

Option	Type	Description
`limit`	number	Max number of requests allowed in the window
`windowMs`	number	Duration of window in milliseconds
`strategy`	'fixed-window' \| 'sliding-window' \| 'token-bucket' \| 'leaky-bucket' \| 'adaptive'	Algorithm used to track requests
`storage`	'memory' \| 'redis' \| 'upstash'	Backend for storing request counters
`headers`	boolean	Whether to add rate-limit headers
`standardHeaders`	boolean	Include legacy `X-RateLimit-*` headers
`statusCode`	number	Response code on limit exceeded (default: `429`)
`message`	string	Error message when blocked
`resources`	Record<string, { limit, windowMs }>	Route-specific throttles
`countryLimits`	Record<string, { limit, windowMs }>	Per-country overrides
`geoProvider`	{ type: 'ipapi' \| 'maxmind' }	Used for country detection
`ddosPrevention`	object	Enable traffic heuristics for spike prevention
`keyGenerator`	Function	Custom function to generate unique request key
`skipFunction`	Function	Skip check conditionally (e.g., internal IPs)

📡 Header Output

When enabled, Lock sets the following headers:

Header	Description
`X-RateLimit-Limit`	Max requests per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Time (seconds) until window resets
`Retry-After`	Delay before retrying (if blocked)

🧪 Example: Per-resource Limits

rateLimit({
  limit: 100,
  windowMs: 60_000,
  resources: {
    '/api/login': { limit: 10, windowMs: 60_000 },
    '/api/posts': { limit: 500, windowMs: 60_000 },
  },
});

🌍 Example: Country-specific Throttling

rateLimit({
  limit: 100,
  windowMs: 60_000,
  geoProvider: { type: 'ipapi' },
  countryLimits: {
    US: { limit: 200, windowMs: 60_000 },
  },
});

🔐 DDoS Protection

Built-in heuristic-based protection:

ddosPrevention: {
  enabled: true,
  requestRateThreshold: 100,
  burstThreshold: 30,
  banDurationMs: 600_000
}

🧩 Storage Backends

Memory (Default)

storage: 'memory',
memoryOptions: {
  max: 10_000,
  ttl: 3600_000
}

Redis

storage: 'redis',
redis: {
  url: 'redis://localhost:6379',
  password: 'secret'
  //pass username if using Redis cloud
}

Upstash

storage: 'upstash',
upstash: {
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!
}

💡 Pro Tip: Custom Key (e.g., User ID)

rateLimit({
  keyGenerator: async ctx => ctx.request.headers['x-user-id'] || 'anonymous',
});

🧪 Testing

Use any HTTP client like curl, Postman, or k6 to simulate burst requests and test blocking.

🛡 Maintained By

Lock Team

security rate-limiting ddos-protection lock

@lock-sdk/core @upstash/redis lru-cache redis

@lock-sdk/main

1.0.0

8 months ago