HyperLimit

High-performance native rate limiter for Node.js with lock-free design, optimized for high-throughput applications. Capable of processing over 9 million requests per second in synthetic benchmarks.

Features

• Lock-free design for high concurrency
• Per-key rate limiting with configurable windows
• Memory-efficient implementation
• Thread-safe operations
• Sliding window support
• Multiple independent rate limiters
• Real-time monitoring and statistics
• Redis-based distributed rate limiting
• Dynamic rate limiting per tenant/API key
• Bypass keys for trusted clients
• Penalty system for abuse prevention
• Customizable key generation
• Framework-specific middleware packages

Installation

Choose the package that matches your framework:

1# For Express.js
2npm install @hyperlimit/express
3
4# For Fastify
5npm install @hyperlimit/fastify
6
7# For HyperExpress
8npm install @hyperlimit/hyperexpress
9
10# Core package (if you want to build custom middleware)
11npm install hyperlimit

Basic Usage

Express.js

1const express = require('express');
2const rateLimiter = require('@hyperlimit/express');
3
4const app = express();
5
6// Example routes using direct configuration
7app.get('/api/public', rateLimiter({
8    key: 'public',
9    maxTokens: 100,
10    window: '1m',
11    sliding: true,
12    block: '30s'
13}), (req, res) => {
14    res.json({ message: 'Public API response' });
15});
16
17// Protected route with more options
18app.get('/api/protected', rateLimiter({
19    key: 'protected',
20    maxTokens: 5,
21    window: '1m',
22    sliding: true,
23    block: '5m',
24    maxPenalty: 3,
25    onRejected: (req, res, info) => {
26        res.status(429).json({
27            error: 'Rate limit exceeded',
28            message: 'Please try again later',
29            retryAfter: info.retryAfter
30        });
31    }
32}), (req, res) => {
33    res.json({ message: 'Protected API response' });
34});
35
36// Custom rate limit with bypass keys
37app.get('/api/custom', rateLimiter({
38    key: 'custom',
39    maxTokens: 20,
40    window: '30s',
41    sliding: true,
42    block: '1m',
43    keyGenerator: req => `${req.ip}-${req.query.userId}`,
44    bypassHeader: 'X-Custom-Key',
45    bypassKeys: ['special-key']
46}), (req, res) => {
47    res.json({ message: 'Custom API response' });
48});

Fastify

1const fastify = require('fastify')();
2const rateLimiter = require('@hyperlimit/fastify');
3
4fastify.get('/api/public', {
5    preHandler: rateLimiter({
6        key: 'public',
7        maxTokens: 100,
8        window: '1m',
9        sliding: true,
10        block: '30s'
11    }),
12    handler: async (request, reply) => {
13        return { message: 'Public API response' };
14    }
15});
16
17// Protected route with more options
18fastify.get('/api/protected', {
19    preHandler: rateLimiter({
20        key: 'protected',
21        maxTokens: 5,
22        window: '1m',
23        sliding: true,
24        block: '5m',
25        maxPenalty: 3,
26        onRejected: (request, reply, info) => {
27            reply.code(429).send({
28                error: 'Rate limit exceeded',
29                message: 'Please try again later',
30                retryAfter: info.retryAfter
31            });
32        }
33    }),
34    handler: async (request, reply) => {
35        return { message: 'Protected API response' };
36    }
37});
38
39// Custom rate limit with bypass keys
40fastify.get('/api/custom', {
41    preHandler: rateLimiter({
42        key: 'custom',
43        maxTokens: 20,
44        window: '30s',
45        sliding: true,
46        block: '1m',
47        keyGenerator: req => `${req.ip}-${req.query.userId}`,
48        bypassHeader: 'X-Custom-Key',
49        bypassKeys: ['special-key']
50    }),
51    handler: async (request, reply) => {
52        return { message: 'Custom API response' };
53    }
54});

HyperExpress

1const HyperExpress = require('hyper-express');
2const rateLimiter = require('@hyperlimit/hyperexpress');
3
4const app = new HyperExpress.Server();
5
6app.get('/api/public', rateLimiter({
7    key: 'public',
8    maxTokens: 100,
9    window: '1m',
10    sliding: true,
11    block: '30s'
12}), (req, res) => {
13    res.json({ message: 'Public API response' });
14});
15
16// Protected route with more options
17app.get('/api/protected', rateLimiter({
18    key: 'protected',
19    maxTokens: 5,
20    window: '1m',
21    sliding: true,
22    block: '5m',
23    maxPenalty: 3,
24    onRejected: (req, res, info) => {
25        res.status(429);
26        res.json({
27            error: 'Rate limit exceeded',
28            message: 'Please try again later',
29            retryAfter: info.retryAfter
30        });
31    }
32}), (req, res) => {
33    res.json({ message: 'Protected API response' });
34});
35
36// Custom rate limit with bypass keys
37app.get('/api/custom', rateLimiter({
38    key: 'custom',
39    maxTokens: 20,
40    window: '30s',
41    sliding: true,
42    block: '1m',
43    keyGenerator: req => `${req.ip}-${req.query.userId}`,
44    bypassHeader: 'X-Custom-Key',
45    bypassKeys: ['special-key']
46}), (req, res) => {
47    res.json({ message: 'Custom API response' });
48});

Core Package Usage

For custom middleware or direct usage:

1const { HyperLimit } = require('hyperlimit');
2
3// Create a rate limiter instance
4const limiter = new HyperLimit({
5    bucketCount: 16384  // Optional: number of hash table buckets (default: 16384)
6});
7
8// Create a limiter for a specific endpoint/feature
9limiter.createLimiter(
10    'api:endpoint1',    // Unique identifier for this limiter
11    100,               // maxTokens: Maximum requests allowed
12    60000,             // window: Time window in milliseconds
13    true,              // sliding: Use sliding window
14    30000,             // block: Block duration in milliseconds
15    5                  // maxPenalty: Maximum penalty points
16);
17
18// Example usage in custom middleware
19function customRateLimiter(options = {}) {
20    const limiter = new HyperLimit();
21    const defaultKey = 'default';
22    
23    // Create the limiter with options
24    limiter.createLimiter(
25        defaultKey,
26        options.maxTokens || 100,
27        typeof options.window === 'string' 
28            ? parseTimeString(options.window) 
29            : (options.window || 60000),
30        options.sliding !== false,
31        typeof options.block === 'string'
32            ? parseTimeString(options.block)
33            : (options.block || 0),
34        options.maxPenalty || 0
35    );
36
37    // Return middleware function
38    return function(req, res, next) {
39        const key = options.keyGenerator?.(req) || req.ip;
40        const allowed = limiter.tryRequest(key);
41
42        if (!allowed) {
43            const info = limiter.getRateLimitInfo(key);
44            return res.status(429).json({
45                error: 'Too many requests',
46                retryAfter: Math.ceil(info.reset / 1000)
47            });
48        }
49
50        // Attach limiter to request for later use
51        req.rateLimit = { limiter, key };
52        next();
53    };
54}
55
56// Helper to parse time strings (e.g., '1m', '30s')
57function parseTimeString(timeStr) {
58    const units = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
59    const match = timeStr.match(/^(\d+)([a-z]+)$/i);
60    if (!match) return parseInt(timeStr, 10);
61    const [, num, unit] = match;
62    return parseInt(num, 10) * (units[unit] || units.ms);
63}

Advanced Features

1. Tenant-Based Rate Limiting

Perfect for SaaS applications with different tiers of service:

1// Simulating a database of tenant configurations
2const tenantConfigs = new Map();
3const tenantLimiters = new Map();
4
5// Example tenant configurations
6tenantConfigs.set('tenant1-key', {
7    name: 'Basic Tier',
8    endpoints: {
9        '/api/data': { maxTokens: 5, window: '10s' },
10        '/api/users': { maxTokens: 2, window: '10s' },
11        '*': { maxTokens: 10, window: '60s' } // Default for unspecified endpoints
12    }
13});
14
15tenantConfigs.set('tenant2-key', {
16    name: 'Premium Tier',
17    endpoints: {
18        '/api/data': { maxTokens: 20, window: '10s' },
19        '/api/users': { maxTokens: 10, window: '10s' },
20        '*': { maxTokens: 50, window: '60s' }
21    }
22});
23
24// Helper to get or create rate limiter for tenant+endpoint
25function getTenantLimiter(tenantKey, endpoint) {
26    const cacheKey = `${tenantKey}:${endpoint}`;
27    
28    if (tenantLimiters.has(cacheKey)) {
29        return tenantLimiters.get(cacheKey);
30    }
31
32    const tenantConfig = tenantConfigs.get(tenantKey);
33    if (!tenantConfig) {
34        return null;
35    }
36
37    // Get endpoint specific config or fallback to default
38    const config = tenantConfig.endpoints[endpoint] || tenantConfig.endpoints['*'];
39    if (!config) {
40        return null;
41    }
42
43    const limiter = rateLimiter({
44        maxTokens: config.maxTokens,
45        window: config.window,
46        keyGenerator: (req) => req.headers['x-api-key']
47    });
48
49    tenantLimiters.set(cacheKey, limiter);
50    return limiter;
51}
52
53// Tenant authentication middleware
54function authenticateTenant(req, res, next) {
55    const apiKey = req.headers['x-api-key'];
56    if (!apiKey) {
57        return res.status(401).json({ error: 'API key required' });
58    }
59
60    const config = tenantConfigs.get(apiKey);
61    if (!config) {
62        return res.status(401).json({ error: 'Invalid API key' });
63    }
64
65    req.tenant = {
66        apiKey,
67        config
68    };
69    next();
70}
71
72// Dynamic rate limiting middleware
73function dynamicRateLimit(req, res, next) {
74    const limiter = getTenantLimiter(req.tenant.apiKey, req.path);
75    if (!limiter) {
76        return res.status(500).json({ error: 'Rate limiter configuration error' });
77    }
78    
79    return limiter(req, res, next);
80}
81
82// Apply tenant authentication to all routes
83app.use(authenticateTenant);
84
85// API endpoints with dynamic rate limiting
86app.get('/api/data', dynamicRateLimit, (req, res) => {
87    res.json({
88        message: 'Data endpoint',
89        tenant: req.tenant.config.name,
90        path: req.path
91    });
92});

2. Distributed Rate Limiting

For applications running across multiple servers:

1const { HyperLimit } = require('hyperlimit');
2
3// Create HyperLimit instance with Redis support
4const limiter = new HyperLimit({
5    bucketCount: 16384,
6    redis: {
7        host: 'localhost',
8        port: 6379,
9        prefix: 'rl:'
10    }
11});
12
13// Configure rate limiter with a distributed key for global coordination
14limiter.createLimiter(
15    'api:endpoint1',      // Local identifier
16    100,                  // Total allowed requests across all servers
17    60000,               // 1 minute window
18    true,                // Use sliding window
19    0,                   // No block duration
20    0,                   // No penalties
21    'api:endpoint1:global' // Distributed key for Redis
22);
23
24// Use in your application
25app.get('/api/endpoint', (req, res) => {
26    const allowed = limiter.tryRequest('api:endpoint1');
27    if (!allowed) {
28        const info = limiter.getRateLimitInfo('api:endpoint1');
29        return res.status(429).json({
30            error: 'Rate limit exceeded',
31            retryAfter: Math.ceil(info.reset / 1000)
32        });
33    }
34    res.json({ message: 'Success' });
35});
36
37// Or use with middleware
38app.get('/api/endpoint', rateLimiter({
39    key: 'api:endpoint1',
40    maxTokens: 100,
41    window: '1m',
42    sliding: true,
43    redis: {
44        host: 'localhost',
45        port: 6379,
46        prefix: 'rl:'
47    }
48}), (req, res) => {
49    res.json({ message: 'Success' });
50});

When Redis is configured:

• Rate limits are synchronized across all application instances
• Tokens are stored and managed in Redis
• Automatic fallback to local rate limiting if Redis is unavailable
• Atomic operations ensure consistency
• Minimal latency overhead

Redis configuration options:

1{
2    host: 'localhost',      // Redis host
3    port: 6379,            // Redis port
4    password: 'optional',   // Redis password
5    db: 0,                 // Redis database number
6    prefix: 'rl:',         // Key prefix for rate limit data
7    connectTimeout: 10000,  // Connection timeout in ms
8    maxRetriesPerRequest: 3 // Max retries per request
9}

3. Penalty System

Handle abuse and violations:

1app.post('/api/sensitive', limiter, (req, res) => {
2    if (violationDetected) {
3        // Add penalty points
4        req.rateLimit.limiter.addPenalty(req.rateLimit.key, 2);
5        return res.status(400).json({ error: 'Violation detected' });
6    }
7    
8    // Later, can remove penalties
9    req.rateLimit.limiter.removePenalty(req.rateLimit.key, 1);
10});

4. Monitoring and Statistics

Track rate limiting status:

1app.get('/status', (req, res) => {
2    const info = req.rateLimit.limiter.getRateLimitInfo(req.rateLimit.key);
3    res.json({
4        limit: info.limit,
5        remaining: info.remaining,
6        reset: info.reset,
7        blocked: info.blocked
8    });
9});

5. Redis Integration Details

When Redis is configured:

• Rate limits are synchronized across all application instances
• Tokens are stored and managed in Redis
• Automatic fallback to local rate limiting if Redis is unavailable
• Atomic operations ensure consistency
• Minimal latency overhead

Redis configuration options:

1{
2    host: 'localhost',      // Redis host
3    port: 6379,            // Redis port
4    password: 'optional',   // Redis password
5    db: 0,                 // Redis database number
6    prefix: 'rl:',         // Key prefix for rate limit data
7    connectTimeout: 10000,  // Connection timeout in ms
8    maxRetriesPerRequest: 3 // Max retries per request
9}

Configuration Options

1interface RateLimiterOptions {
2    // Core Options
3    maxTokens: number;      // Maximum requests allowed
4    window: string|number;  // Time window (e.g., '1m', '30s', or milliseconds)
5    sliding?: boolean;      // Use sliding window (default: true)
6    block?: string|number;  // Block duration after limit exceeded
7    
8    // Advanced Options
9    maxPenalty?: number;     // Maximum penalty points
10    bypassHeader?: string;   // Header for bypass keys
11    bypassKeys?: string[];   // List of bypass keys
12    keyGenerator?: (req) => string;  // Custom key generation
13    
14    // Distributed Options
15    redis?: Redis;           // Redis client for distributed mode
16    
17    // Response Handling
18    onRejected?: (req, res, info) => void;  // Custom rejection handler
19}

Response Headers

The middleware automatically sets these headers:

• X-RateLimit-Limit: Maximum allowed requests
• X-RateLimit-Remaining: Remaining requests in window
• X-RateLimit-Reset: Seconds until limit resets

Performance Benchmarks

HyperLimit achieves exceptional performance through:

• Native C++ implementation
• Lock-free atomic operations
• No external dependencies
• Efficient token bucket algorithm
• Minimal memory footprint

Test Type	Requests/sec	Latency (ms)
Single Key	~9.1M	0.11
Multi-Key	~7.5M	0.13
Concurrent	~3.2M	0.31

Detailed Benchmark Results

Tests performed on a MacBook Pro with Apple M3 Max, 64GB RAM. Each test measures:

• Single Key: Processing 1,000,000 requests through a single key
• Multi-Key: Processing 100,000 requests with unique keys
• Concurrent: Processing 100,000 concurrent requests with unique keys

Small Hash Table (1K)

Test Type	HyperLimit	Rate Limiter Flexible	Express Rate Limit	Req/sec (HyperLimit)
Single Key	109.887ms	176.971ms	8.359s	~9.1M
Multi-Key	14.747ms	90.725ms	906.47ms	~6.8M
Concurrent	30.99ms	96.715ms	995.496ms	~3.2M

Default Hash Table (16K)

Test Type	HyperLimit	Rate Limiter Flexible	Express Rate Limit	Req/sec (HyperLimit)
Single Key	106.497ms	174.073ms	9.338s	~9.4M
Multi-Key	13.311ms	84.9ms	985.935ms	~7.5M
Concurrent	34.857ms	101.525ms	986.597ms	~2.9M

Large Hash Table (64K)

Test Type	HyperLimit	Rate Limiter Flexible	Express Rate Limit	Req/sec (HyperLimit)
Single Key	109.467ms	184.259ms	9.374s	~9.1M
Multi-Key	12.12ms	77.029ms	935.926ms	~8.3M
Concurrent	34.236ms	90.011ms	1.079s	~2.9M

Key findings:

• Up to 85x faster than Express Rate Limit
• Up to 7x faster than Rate Limiter Flexible
• Consistent performance across different hash table sizes
• Exceptional multi-key and concurrent performance
• Sub-millisecond latency in most scenarios

Note: These are synthetic benchmarks measuring raw performance without network overhead or real-world conditions. Actual performance will vary based on your specific use case and environment.

Examples

Check out the examples directory for:

• Basic rate limiting setups
• Tenant-based configurations
• Distributed rate limiting
• Penalty system implementation
• Monitoring and statistics
• Custom key generation
• Framework-specific implementations

Best Practices

1. Key Generation:

   • Use meaningful keys (e.g., ${req.ip}-${req.path})
   • Consider user identity for authenticated routes
   • Combine multiple factors for granular control

2. Window Selection:

   • Use sliding windows for smooth rate limiting
   • Match window size to endpoint sensitivity
   • Consider user experience when setting limits

3. Distributed Setup:

   • Enable Redis for multi-server deployments
   • Set appropriate prefix to avoid key collisions
   • Monitor Redis connection health

4. Penalty System:

   • Start with small penalties
   • Implement gradual penalty removal
   • Log penalty events for analysis

5. Monitoring:

   • Regularly check rate limit status
   • Monitor bypass key usage
   • Track penalty patterns

Building from Source

1# Clone the repository
2git clone https://github.com/mehrantsi/hyperlimit.git
3
4# Install dependencies
5cd hyperlimit
6npm install
7
8# Build
9npm run build
10
11# Run tests
12npm test
13
14# Run examples
15npm run example:express
16npm run example:fastify
17npm run example:hyperexpress

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. See CONTRIBUTING.md for more information.

License

MIT License - see LICENSE file for details