# @bernierllc/rate-limiter

High-performance rate limiting with multiple algorithms and storage backends for Node.js applications.

## Installation

```bash
npm install @bernierllc/rate-limiter
```

For Redis support, install the Redis client:
```bash
# Using node-redis
npm install redis

# Or using ioredis
npm install ioredis
```

## Usage

### Basic Rate Limiting

```typescript
import { createRateLimiter } from '@bernierllc/rate-limiter';

// Create a rate limiter with default token bucket algorithm
const rateLimiter = createRateLimiter({
  algorithm: 'token-bucket',
  limit: 100,
  windowMs: 60000, // 1 minute
  storage: 'memory'
});

// Check if request is allowed
const result = await rateLimiter.check('user-123');

if (result.allowed) {
  console.log(`Request allowed. ${result.remaining} requests remaining.`);
} else {
  console.log(`Rate limit exceeded. Try again in ${result.reset - Date.now()}ms.`);
}
```

### Express Middleware

```typescript
import express from 'express';
import { createRateLimiter, createExpressMiddleware } from '@bernierllc/rate-limiter';

const app = express();

// Create rate limiter
const rateLimiter = createRateLimiter({
  algorithm: 'sliding-window',
  limit: 50,
  windowMs: 60000,
  storage: 'memory'
});

// Apply middleware
app.use('/api', createExpressMiddleware(rateLimiter, {
  keyGenerator: (req) => req.ip,
  skip: (req) => req.method === 'GET' && req.path === '/health',
  handler: (req, res) => {
    res.status(429).json({ error: 'Too many requests' });
  },
  contextBuilder: (req) => ({
    key: req.ip,
    path: req.path,
    method: req.method,
    userId: req.user?.id
  })
}));
```

### Fastify Plugin

```typescript
import fastify from 'fastify';
import { createRateLimiter, createFastifyPlugin } from '@bernierllc/rate-limiter';

const app = fastify();

const rateLimiter = createRateLimiter({
  algorithm: 'fixed-window',
  limit: 200,
  windowMs: 60000
});

app.register(createFastifyPlugin(rateLimiter, {
  points: request => (request.routerPath === '/upload' ? 5 : 1)
}));
```

### Next.js Middleware

```typescript
import type { NextApiHandler } from 'next';
import { createRateLimiter, createNextMiddleware } from '@bernierllc/rate-limiter';

const limiter = createRateLimiter({
  algorithm: 'token-bucket',
  limit: 120,
  windowMs: 60000
});

const rateLimit = createNextMiddleware(limiter);

const handler: NextApiHandler = async (req, res) => {
  await rateLimit(req, res, async () => {
    res.status(200).json({ ok: true, remaining: req.rateLimit?.remaining });
  });
};

export default handler;
```

### Redis Storage Backend

```typescript
import { createRateLimiter } from '@bernierllc/rate-limiter';
import { createClient } from 'redis';

// Using node-redis
const redisClient = createClient({ url: 'redis://localhost:6379' });
await redisClient.connect();

const rateLimiter = createRateLimiter({
  algorithm: 'fixed-window',
  limit: 1000,
  windowMs: 3600000, // 1 hour
  storage: {
    type: 'redis',
    client: redisClient,
    keyPrefix: 'rl:'
  }
});
```

### Using ioredis

```typescript
import { createRateLimiter } from '@bernierllc/rate-limiter';
import Redis from 'ioredis';

const redisClient = new Redis({
  host: 'localhost',
  port: 6379
});

const rateLimiter = createRateLimiter({
  algorithm: 'sliding-window',
  limit: 500,
  windowMs: 900000, // 15 minutes
  storage: {
    type: 'redis',
    client: redisClient,
    keyPrefix: 'api_limits:'
  }
});
```

### Database Storage Backend

```typescript
import { createRateLimiter } from '@bernierllc/rate-limiter';

const adapter = {
  get: async (key) => database.fetchRateLimit(key),
  set: async (key, data, ttl) => database.upsertRateLimit(key, data, ttl),
  increment: async (key, amount = 1) => database.incrementRateLimit(key, amount),
  delete: async (key) => database.removeRateLimit(key),
  expire: async (key, ttl) => database.setExpiry(key, ttl)
};

const rateLimiter = createRateLimiter({
  limit: 100,
  windowMs: 60000,
  storage: {
    type: 'database',
    adapter,
    keyPrefix: 'api:'
  }
});
```

## API Reference

### createRateLimiter(options)

Creates a rate limiter instance with the specified configuration.

#### Options

- **limit** (`number`): Maximum number of requests allowed in the base configuration (required)
- **windowMs** (`number`): Time window in milliseconds for the base configuration (required)
- **algorithm?** (`string`): Algorithm to use for the base configuration (`'token-bucket'`, `'sliding-window'`, `'fixed-window'`, `'leaky-bucket'`)
- **bucketSize? / refillRate? / tokensPerRequest? / precision? / leakRate?** (`number`): Algorithm-specific overrides for the base configuration
- **storage?** (`string | object`): Storage backend configuration
  - `'memory'` - In-memory storage (default)
  - `{ type: 'redis', client: RedisClient | IORedisClient, keyPrefix?: string }` - Redis-backed storage
  - `{ type: 'database', adapter: RateLimitDatabaseAdapter, keyPrefix?: string }` - Database-backed storage using custom adapter
- **skipOnError?** (`boolean`): When `true`, allows traffic if the storage backend fails (default `false`)
- **onLimitReached?** (`function`): Callback invoked when a limit is exceeded. Receives `(key, result, context)`
- **customRules?** (`RateLimitRule[]`): Array of context-aware rules that can override algorithm, limits, or storage key prefix per request

#### Returns

Returns a `RateLimiter` instance with the following methods:

- `check(key: string, options?: RateLimitCheckOptions): Promise<RateLimitResult>` - Check if request is allowed with optional points/context
- `reset(key: string): Promise<boolean>` - Reset limits for a key
- `getUsage(key: string): Promise<UsageInfo>` - Get current usage stats

### createExpressMiddleware(rateLimiter, options?)

Creates Express middleware from a rate limiter instance.

#### Options

- **keyGenerator?** (`function`): Function to generate rate limit key from request
  - Default: `(req) => req.ip`

- **skip?** (`function`): Function to skip rate limiting for certain requests
  - Default: `() => false`

- **handler?** (`function`): Custom handler when limit exceeded
  - Default: Sends 429 status with standard message

- **points?** (`number | function`): Number of points consumed per request or resolver function
- **contextBuilder?** (`function`): Builds contextual metadata passed to custom rules and storage keys

- **legacyHeaders?** (`boolean`): Include legacy `X-RateLimit-*` headers
  - Default: `false`

- **standardHeaders?** (`boolean`): Include standard `RateLimit-*` headers
  - Default: `true`

- **requestPropertyName?** (`string`): Property name to attach rate limit info to request
  - Default: `'rateLimit'`

### createFastifyPlugin(rateLimiter, options?)

Registers rate limiting as a Fastify `onRequest` hook.

- Shares the same option signatures as `createExpressMiddleware`, including `points` and `contextBuilder`.
- Automatically sets response headers using Fastify's reply helpers.

### createNextMiddleware(rateLimiter, options?)

Provides a drop-in middleware for Next.js API routes.

- Supports the same options as `createExpressMiddleware`.
- Attaches rate limit metadata to the request object and sets response headers via `setHeader`.

### Rate Limit Algorithms

#### Token Bucket
- Allows bursts up to bucket capacity
- Refills tokens at steady rate
- Best for: APIs that can handle bursts

#### Sliding Window
- Precise rate limiting over moving time window
- Higher memory usage but accurate
- Best for: Strict rate enforcement

#### Fixed Window
- Simple time windows with reset points
- Lower memory usage, allows bursts at window boundaries
- Best for: Simple rate limiting needs

#### Leaky Bucket
- Smooths out bursts by processing at steady rate
- Queues requests up to bucket capacity
- Best for: Traffic shaping and smoothing

## Configuration Examples

### API Rate Limiting

```typescript
// Public API - 1000 requests per hour
const publicApi = createRateLimiter({
  algorithm: 'sliding-window',
  limit: 1000,
  windowMs: 3600000,
  storage: 'redis' // Distributed limiting
});

// Premium API - 5000 requests per hour  
const premiumApi = createRateLimiter({
  algorithm: 'token-bucket',
  limit: 5000,
  windowMs: 3600000,
  storage: 'redis'
});
```

### Different Endpoints

```typescript
// Login attempts - strict limiting
const loginLimiter = createRateLimiter({
  algorithm: 'fixed-window',
  limit: 5,
  windowMs: 900000, // 15 minutes
  storage: 'memory'
});

// File uploads - burst handling
const uploadLimiter = createRateLimiter({
  algorithm: 'token-bucket', 
  limit: 10,
  windowMs: 60000, // 1 minute
  storage: 'memory'
});

app.post('/login', createExpressMiddleware(loginLimiter));
app.post('/upload', createExpressMiddleware(uploadLimiter));
```

### Advanced Middleware Configuration

```typescript
const advancedMiddleware = createExpressMiddleware(rateLimiter, {
  // Use user ID for authenticated users, IP for anonymous
  keyGenerator: (req) => {
    return req.user?.id || req.ip;
  },
  
  // Skip rate limiting for admin users
  skip: (req) => {
    return req.user?.role === 'admin';
  },
  
  // Custom response for rate limit exceeded
  handler: (req, res, result) => {
    const retryAfter = Math.ceil((result.reset - Date.now()) / 1000);

    res.status(429).json({
      error: 'Rate limit exceeded',
      retryAfter,
      limit: result.limit,
      remaining: result.remaining
    });
  },

  // Include both standard and legacy headers
  standardHeaders: true,
  legacyHeaders: true,

  // Attach rate limit info to request for logging
  requestPropertyName: 'rateLimitInfo',

  // Provide additional context for custom rules or analytics
  contextBuilder: (req) => ({
    key: req.user?.id || req.ip,
    userId: req.user?.id,
    plan: req.user?.plan || 'free'
  })
});
```

## Integration Status

### Logger Integration
**Status**: Not applicable

**Justification**: This is a pure utility package with no runtime state, side effects, or error conditions that require logging. The RateLimiter class is stateless and deterministic - it simply calculates rate limit status based on request counts and time windows. All errors are returned as structured results that calling code can handle, and there are no background operations, network calls, or state changes that would benefit from structured logging.

**Pattern**: Pure functional utility - no logger integration needed.

### NeverHub Integration
**Status**: Not applicable

**Justification**: This is a core utility package that provides rate limiting functionality. It does not participate in service discovery, event publishing, or service mesh operations. Rate limiting is a stateless utility operation that doesn't require service registration or discovery.

**Pattern**: Core utility - no service mesh integration needed.

### Docs-Suite Integration
**Status**: Ready

**Format**: TypeDoc-compatible JSDoc comments are included throughout the source code. All public APIs are documented with examples and type information.

## Error Handling

All rate limiter methods return structured results instead of throwing errors:

```typescript
const result = await rateLimiter.check('user-123');

if (!result.allowed) {
  // Handle rate limit exceeded
  console.log(`Blocked: ${result.remaining} remaining, reset at ${result.reset}`);
}
```

For storage backend errors (Redis connection issues, etc.), the rate limiter will:
1. Log the error (if logger integration is available)
2. Fall back to allowing the request (fail-open policy)
3. Return appropriate error information in the result

## Performance

- **Memory Storage**: Handles 100k+ requests/second per algorithm instance
- **Redis Storage**: Performance depends on Redis server and network latency
- **Algorithms**: Token bucket and fixed window are most performant
- **Memory Usage**: Sliding window uses most memory, fixed window uses least

## Testing

```bash
# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test suite
npm test -- algorithms/token-bucket.test.ts
```

## See Also

- [@bernierllc/connection-parser](../connection-parser) - Redis connection string parsing (used internally)
- [@bernierllc/crypto-utils](../crypto-utils) - Secure token generation for rate limiting keys

## License

Copyright (c) 2025 Bernier LLC. All rights reserved.