### Initialize and Use Rate Limiter SDK

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/sdk/README.md

Quick start example demonstrating how to initialize the RateLimiter with your service URL and API key, and perform a basic check. Handles rate limit exceeded scenarios.

```typescript
import { RateLimiter } from '@rajvardhan6403/rate-limiter-sdk';

const limiter = new RateLimiter({
  serviceUrl: 'https://distributed-rate-limiter-production-82bf.up.railway.app',
  apiKey: 'your-api-key',
});

const result = await limiter.check({ identifier: 'user-123' });

if (!result.allowed) {
  console.log('Rate limit exceeded. Retry after:', result.retryAfterSeconds, 'seconds');
} else {
  console.log('Request allowed. Remaining:', result.remaining);
}
```

--------------------------------

### Clone and Start Distributed Rate Limiter with Docker Compose

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

Steps to clone the repository and start the distributed rate limiter service locally using Docker Compose. Assumes Docker Desktop is installed.

```bash
git clone https://github.com/raj-deshmukh6403/distributed-rate-limiter.git
cd distributed-rate-limiter
docker compose up --build
```

--------------------------------

### Install Rate Limiter SDK

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/sdk/README.md

Install the SDK using npm. This is the first step to integrate rate limiting into your application.

```bash
npm install @rajvardhan6403/rate-limiter-sdk
```

--------------------------------

### Local Development Setup

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

Instructions for setting up and running the distributed rate limiter locally using Docker.

```APIDOC
## Running Locally

### Prerequisites
- Docker Desktop
- Git

### Start Everything
```bash
git clone https://github.com/raj-deshmukh6403/distributed-rate-limiter.git
cd distributed-rate-limiter
docker compose up --build
```

### Service URLs
| Service | URL |
|---------|-----|
| API via Nginx | http://localhost |
| Service Instance 1 | http://localhost:8080 |
| Service Instance 2 | http://localhost:8081 |
| Prometheus | http://localhost:9090 |
| Grafana | http://localhost:3000 (admin/admin) |
| Redis | localhost:6379 |
```

--------------------------------

### Python Integration Example

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Direct HTTP API usage from Python applications.

```APIDOC
## POST /api/v1/check (Python HTTP Client)

### Description
Demonstrates how to use the rate limiter's check endpoint directly from a Python application using the `requests` library.

### Method
POST

### Endpoint
`/api/v1/check`

### Parameters
#### Request Body
- **apiKey** (string) - Required - Your API key for authentication.
- **identifier** (string) - Required - A unique identifier for the entity being rate limited (e.g., IP address, user ID).
- **cost** (number) - Optional - The cost of the request in tokens. Defaults to 1.

### Request Example
```python
import requests

class RateLimiter:
    def __init__(self, service_url: str, api_key: str):
        self.service_url = service_url.rstrip('/')
        self.api_key = api_key

    def check(self, identifier: str, cost: int = 1) -> dict:
        response = requests.post(
            f'{self.service_url}/api/v1/check',
            json={
                'apiKey': self.api_key,
                'identifier': identifier,
                'cost': cost
            },
            timeout=3
        )
        return response.json()

limiter = RateLimiter(
    service_url='https://distributed-rate-limiter-production-82bf.up.railway.app',
    api_key='your-api-key'
)

result = limiter.check(identifier='user-123')

if not result['allowed']:
    print(f"Rate limited. Retry after {result['retryAfterSeconds']} seconds")
else:
    print(f"Allowed. {result['remaining']} requests remaining")
```

### Response
#### Success Response (200)
- **allowed** (boolean) - Indicates if the request is allowed.
- **remaining** (number) - The number of requests remaining in the current window.
- **limit** (number) - The total limit configured for the window.
- **windowSeconds** (number) - The duration of the rate limiting window in seconds.
- **resetAtEpochMs** (number) - The timestamp (in epoch milliseconds) when the rate limiting window resets.
- **retryAfterSeconds** (number) - The number of seconds to wait before retrying if the request is denied. 0 if allowed.

#### Response Example
```json
{
  "allowed": false,
  "remaining": 0,
  "limit": 10,
  "windowSeconds": 60,
  "resetAtEpochMs": 1678886400000,
  "retryAfterSeconds": 15
}
```
```

--------------------------------

### Docker Compose Startup and Testing Commands

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Provides commands to clone the repository, start the Docker Compose services, and test the distributed rate limiting functionality by registering a key.

```bash
# Start all services
git clone https://github.com/raj-deshmukh6403/distributed-rate-limiter.git
cd distributed-rate-limiter
docker compose up --build

# Service URLs after startup:
# API via Nginx:      http://localhost
# Service Instance 1: http://localhost:8080
# Service Instance 2: http://localhost:8081
# Prometheus:         http://localhost:9090
# Grafana:            http://localhost:3000 (admin/admin)
# Redis:              localhost:6379

# Test distributed rate limiting
# Register a key with limit of 5 requests per 30 seconds
curl -X POST http://localhost/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"algorithm":"sliding_window","limit":5,"windowSeconds":30}'
```

--------------------------------

### Python Integration Example for Rate Limiter

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

This Python example demonstrates direct HTTP API usage for rate limiting. It includes a RateLimiter class to check rate limits by sending POST requests to the service URL.

```python
import requests
from typing import Optional

class RateLimiter:
    def __init__(self, service_url: str, api_key: str):
        self.service_url = service_url.rstrip('/')
        self.api_key = api_key

    def check(self, identifier: str, cost: int = 1) -> dict:
        """Check if request should be allowed."""
        response = requests.post(
            f'{self.service_url}/api/v1/check',
            json={
                'apiKey': self.api_key,
                'identifier': identifier,
                'cost': cost
            },
            timeout=3
        )
        return response.json()

# Usage
limiter = RateLimiter(
    service_url='https://distributed-rate-limiter-production-82bf.up.railway.app',
    api_key='your-api-key'
)

# Check rate limit
result = limiter.check(identifier='user-123')

if not result['allowed']:
    print(f"Rate limited. Retry after {result['retryAfterSeconds']} seconds")
else:
    print(f"Allowed. {result['remaining']} requests remaining")

```

--------------------------------

### Run 6 requests - the 6th should return 429

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

This example demonstrates how to test the rate limiter by sending multiple requests and observing the 429 Too Many Requests response for the sixth request. Ensure the service is running locally on http://localhost:80.

```bash
for i in {1..6}; do
  echo "Request $i:"
  curl -s -X POST http://localhost/api/v1/check \
    -H "Content-Type: application/json" \
    -d '{"apiKey":"YOUR_KEY","identifier":"test-user","cost":1}' | jq .
done
```

--------------------------------

### Register API Key with Token Bucket Algorithm

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/sdk/README.md

Register a new API key using cURL. This example uses the 'token_bucket' algorithm, suitable for allowing short bursts while controlling sustained traffic.

```bash
curl -X POST .../api/v1/keys \
  -d '{"algorithm":"token_bucket","limit":100,"windowSeconds":60}'
```

--------------------------------

### Register API Key with Sliding Window Algorithm

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/sdk/README.md

Register a new API key using cURL. This example uses the 'sliding_window' algorithm, which is recommended for precise per-user enforcement.

```bash
curl -X POST https://distributed-rate-limiter-production-82bf.up.railway.app/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"algorithm":"sliding_window","limit":100,"windowSeconds":60}'
```

--------------------------------

### Direct HTTP API Usage

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

Examples of how to use the direct HTTP API for rate limiting checks from various programming languages.

```APIDOC
## Direct HTTP API

### Python Example
```python
import requests

response = requests.post(
    'https://distributed-rate-limiter-production-82bf.up.railway.app/api/v1/check',
    json={'apiKey': 'your-api-key', 'identifier': 'user-123', 'cost': 1}
)
data = response.json()
if not data['allowed']:
    print(f"Rate limited. Retry after {data['retryAfterSeconds']} seconds")
```

### Go Example
```go
resp, _ := http.Post(
    "https://distributed-rate-limiter-production-82bf.up.railway.app/api/v1/check",
    "application/json",
    strings.NewReader(`{"apiKey":"your-key","identifier":"user-123","cost":1}`),
)
```
```

--------------------------------

### GET /api/v1/keys/{apiKey} - Get Policy

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

Retrieves the rate limiting policy associated with a given API key.

```APIDOC
## GET /api/v1/keys/{apiKey}

### Description
Retrieves the rate limiting policy associated with a given API key.

### Method
GET

### Endpoint
/api/v1/keys/{apiKey}

### Parameters
#### Path Parameters
- **apiKey** (string) - Required - The API key whose policy is to be retrieved.
```

--------------------------------

### Integrate Express Middleware for All Routes

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/sdk/README.md

Apply the rate limiter middleware to all routes in an Express application. This example identifies users by their IP address.

```typescript
import express from 'express';
import { RateLimiter } from '@rajvardhan6403/rate-limiter-sdk';

const app = express();

const limiter = new RateLimiter({
  serviceUrl: 'https://distributed-rate-limiter-production-82bf.up.railway.app',
  apiKey: 'your-api-key',
});

// Apply to all routes — identifies users by IP address
app.use(limiter.middleware());

app.get('/hello', (req, res) => {
  res.json({ message: 'Hello World' });
});

app.listen(3000);
```

--------------------------------

### Get API Key Policy

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Retrieves the rate limit policy configuration for a specific API key. This includes the limit, window size, and the algorithm used.

```bash
curl -X GET https://distributed-rate-limiter-production-82bf.up.railway.app/api/v1/keys/your-api-key
```

--------------------------------

### Create Express Middleware with createExpressMiddleware()

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Use createExpressMiddleware() as an alternative factory for Express middleware, offering more control over options like custom identifier extraction and cost without instantiating the RateLimiter class directly within the middleware setup.

```typescript
import express from 'express';
import { RateLimiter } from '@rajvardhan6403/rate-limiter-sdk';
import { createExpressMiddleware } from '@rajvardhan6403/rate-limiter-sdk/middleware/express';

const app = express();

const limiter = new RateLimiter({
  serviceUrl: 'http://localhost',
  apiKey: 'your-api-key',
});

// Create middleware with custom options
const rateLimitMiddleware = createExpressMiddleware(limiter, {
  identifier: (req) => req.headers['x-api-key'] as string || req.ip,
  cost: 1,
});

// Apply to specific routes
app.use('/api/v1', rateLimitMiddleware);

app.get('/api/v1/users', (req, res) => {
  res.json({ users: [] });
});
```

--------------------------------

### Initialize RateLimiter SDK with Minimal Configuration

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Initializes the RateLimiter SDK with the essential parameters: service URL and API key. Other options will use their default values.

```typescript
// Minimal configuration
const limiterMinimal = new RateLimiter({
  serviceUrl: 'http://localhost',
  apiKey: 'your-api-key',
});
```

--------------------------------

### Initialize RateLimiter SDK with Full Configuration

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Initializes the RateLimiter SDK with a comprehensive set of options, including service URL, API key, fail-open behavior, HTTP timeout, and local cache TTL.

```typescript
import { RateLimiter } from '@rajvardhan6403/rate-limiter-sdk';

// Full configuration with all options
const limiter = new RateLimiter({
  serviceUrl: 'https://distributed-rate-limiter-production-82bf.up.railway.app',
  apiKey: 'your-api-key',
  failOpen: true,           // Allow requests if service is down (default: true)
  timeoutMs: 3000,          // HTTP timeout in milliseconds (default: 3000)
  localCacheTtlMs: 1000,    // Cache deny decisions for 1 second (default: 1000)
});
```

--------------------------------

### Configure SDK for Local Instance

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/sdk/README.md

Configure the SDK to point to a locally self-hosted rate limiter service. Update the 'serviceUrl' to 'http://localhost'.

```typescript
const limiter = new RateLimiter({
  serviceUrl: 'http://localhost',
  apiKey: 'your-api-key',
});
```

--------------------------------

### npm SDK Usage

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

Demonstrates how to use the npm SDK for Node.js and TypeScript to integrate rate limiting into your application.

```APIDOC
## npm SDK Integration

### Installation
```bash
npm install @rajvardhan6403/rate-limiter-sdk
```

### Basic Usage
```typescript
import { RateLimiter } from '@rajvardhan6403/rate-limiter-sdk';

const limiter = new RateLimiter({
  serviceUrl: 'https://distributed-rate-limiter-production-82bf.up.railway.app',
  apiKey: 'your-api-key',
  failOpen: true,
  timeoutMs: 3000,
});

const result = await limiter.check({ identifier: req.ip });

if (!result.allowed) {
  return res.status(429).json({ error: 'Rate limit exceeded' });
}
```

### Express Middleware
```typescript
import express from 'express';
import { RateLimiter } from '@rajvardhan6403/rate-limiter-sdk';

const app = express();
const limiter = new RateLimiter({
  serviceUrl: 'https://distributed-rate-limiter-production-82bf.up.railway.app',
  apiKey: 'your-api-key',
});

app.use(limiter.middleware());  // all routes are now rate limited
```
```

--------------------------------

### Go HTTP API Client for Rate Limiter

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Demonstrates how to use the distributed rate limiter's HTTP API from a Go application. Includes request and response structures for checking limits.

```go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "time"
)

type CheckRequest struct {
    APIKey     string `json:"apiKey"`
    Identifier string `json:"identifier"`
    Cost       int    `json:"cost"`
}

type CheckResponse struct {
    Allowed           bool  `json:"allowed"`
    Remaining         int   `json:"remaining"`
    ResetAtEpochMs    int64 `json:"resetAtEpochMs"`
    RetryAfterSeconds int   `json:"retryAfterSeconds"`
    Limit             int   `json:"limit"`
    WindowSeconds     int   `json:"windowSeconds"`
}

type RateLimiter struct {
    ServiceURL string
    APIKey     string
    Client     *http.Client
}

func NewRateLimiter(serviceURL, apiKey string) *RateLimiter {
    return &RateLimiter{
        ServiceURL: serviceURL,
        APIKey:     apiKey,
        Client:     &http.Client{Timeout: 3 * time.Second},
    }
}

func (r *RateLimiter) Check(identifier string, cost int) (*CheckResponse, error) {
    reqBody := CheckRequest{
        APIKey:     r.APIKey,
        Identifier: identifier,
        Cost:       cost,
    }

    body, _ := json.Marshal(reqBody)
    resp, err := r.Client.Post(
        r.ServiceURL+"/api/v1/check",
        "application/json",
        bytes.NewBuffer(body),
    )
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result CheckResponse
    json.NewDecoder(resp.Body).Decode(&result)
    return &result, nil
}

func main() {
    limiter := NewRateLimiter(
        "https://distributed-rate-limiter-production-82bf.up.railway.app",
        "your-api-key",
    )

    result, err := limiter.Check("user-123", 1)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    if !result.Allowed {
        fmt.Printf("Rate limited. Retry after %d seconds\n", result.RetryAfterSeconds)
    } else {
        fmt.Printf("Allowed. %d requests remaining\n", result.Remaining)
    }
}
```

--------------------------------

### Configure Rate Limiter Options

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/sdk/README.md

Initialize the RateLimiter with custom configuration options, including service URL, API key, fail-open behavior, HTTP timeout, and local cache TTL.

```typescript
const limiter = new RateLimiter({
  serviceUrl: 'https://your-service-url',  // required
  apiKey: 'your-api-key',                  // required
  failOpen: true,                          // allow requests if service is down (default: true)
  timeoutMs: 3000,                         // HTTP timeout in ms (default: 3000)
  localCacheTtlMs: 1000,                   // cache deny decisions for 1s (default: 1000)
});
```

--------------------------------

### Check Requests with API Key

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

After obtaining an API key, use this command to check requests against the rate limiter. Replace YOUR_KEY with the actual API key. Running this multiple times will demonstrate the rate limiting in action.

```bash
curl -X POST https://distributed-rate-limiter-production-82bf.up.railway.app/api/v1/check \
  -H "Content-Type: application/json" \
  -d '{"apiKey":"YOUR_KEY","identifier":"test-user","cost":1}'
```

--------------------------------

### Docker Compose for Self-Hosted Deployment

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Sets up a complete local environment for the distributed rate limiter using Docker Compose. Includes Redis, two service instances, Nginx for load balancing, and monitoring tools.

```yaml
# docker-compose.yml - Full stack deployment
services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    command: redis-server --save 60 1

  service1:
    build: ./service
    environment:
      - SPRING_DATA_REDIS_HOST=redis
      - SPRING_DATA_REDIS_PORT=6379
      - SERVER_PORT=8080
    ports:
      - "8080:8080"
    depends_on:
      - redis

  service2:
    build: ./service
    environment:
      - SPRING_DATA_REDIS_HOST=redis
      - SPRING_DATA_REDIS_PORT=6379
      - SERVER_PORT=8080
    ports:
      - "8081:8080"
    depends_on:
      - redis

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - service1
      - service2

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml:ro

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      GF_SECURITY_ADMIN_PASSWORD: admin
    depends_on:
      - prometheus
```

--------------------------------

### Register API Key with Rate Limiter

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

Use this command to register a new API key with the rate limiter service. Specify the desired algorithm, limit, and window in seconds.

```bash
curl -X POST https://distributed-rate-limiter-production-82bf.up.railway.app/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"algorithm":"sliding_window","limit":5,"windowSeconds":30}'
```

--------------------------------

### Self-Host Rate Limiter Service

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/sdk/README.md

Instructions for self-hosting the distributed rate limiter service using Docker. Clone the repository, navigate to the directory, and run the Docker compose command.

```bash
git clone https://github.com/raj-deshmukh6403/distributed-rate-limiter
cd distributed-rate-limiter
docker compose up --build
```

--------------------------------

### Register API Key with Token Bucket

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Registers a new API key using the token bucket algorithm, suitable for traffic patterns that allow short bursts. Configuration includes the limit and window duration.

```bash
curl -X POST https://distributed-rate-limiter-production-82bf.up.railway.app/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "token_bucket",
    "limit": 50,
    "windowSeconds": 30
  }'
```

--------------------------------

### Correct Distributed Rate Limiting with Redis

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

Demonstrates the correct approach where all servers interact with a shared Redis counter, ensuring consistent rate limit enforcement across instances.

```text
User → Server 1 → Redis counter = 1  ✅
User → Server 2 → Redis counter = 2  ✅
User → Server 3 → Redis counter = 3  ✅
```

--------------------------------

### createExpressMiddleware() - Express Standalone

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Alternative middleware factory for more control over middleware options without calling the class method.

```APIDOC
## Create Express Middleware Standalone

### Description
Provides a standalone factory function to create Express middleware with granular control over options.

### Method
USE (Express middleware)

### Endpoint
Applies to routes specified during middleware setup.

### Parameters
#### Middleware Options (Object Argument)
- **identifier** (function) - Required - A function that takes the Express request object and returns a unique identifier string.
- **cost** (number) - Optional - The cost of each request in tokens. Defaults to 1.

### Request Example
```typescript
import express from 'express';
import { RateLimiter } from '@rajvardhan6403/rate-limiter-sdk';
import { createExpressMiddleware } from '@rajvardhan6403/rate-limiter-sdk/middleware/express';

const app = express();
const limiter = new RateLimiter({ serviceUrl: '...', apiKey: '...' });

const rateLimitMiddleware = createExpressMiddleware(limiter, {
  identifier: (req) => req.headers['x-api-key'] as string || req.ip,
  cost: 1
});

app.use('/api/v1', rateLimitMiddleware);
```

### Response Headers (Set by Middleware)
- **X-RateLimit-Limit** (number) - Total requests allowed in the window.
- **X-RateLimit-Remaining** (number) - Requests remaining in the current window.
- **X-RateLimit-Reset** (number) - The timestamp (epoch ms) when the window resets.
- **Retry-After** (number) - Seconds to wait before retrying (only on 429 responses).
```

--------------------------------

### Register API Key with Sliding Window

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Registers a new API key with the sliding window algorithm for precise per-user rate limiting. Requires specifying the limit and window duration in seconds.

```bash
curl -X POST https://distributed-rate-limiter-production-82bf.up.railway.app/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "sliding_window",
    "limit": 100,
    "windowSeconds": 60
  }'
```

--------------------------------

### Check Rate Limit via Direct HTTP API (Go)

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

Make a POST request to the /api/v1/check endpoint using Go's http package to check rate limits. Requires constructing a JSON payload and specifying the content type.

```go
resp, _ := http.Post(
    "https://distributed-rate-limiter-production-82bf.up.railway.app/api/v1/check",
    "application/json",
    strings.NewReader(`{"apiKey":"your-key","identifier":"user-123","cost":1}`),
)
```

--------------------------------

### Docker Compose for Full Stack Deployment

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

This command orchestrates the entire rate limiter stack, including the Spring Boot service, Redis, Nginx, and monitoring tools, using Docker Compose.

```bash
docker-compose up
```

--------------------------------

### Broken Rate Limiting on Single Server

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

Illustrates how rate limiting fails when each server instance maintains its own counter, leading to users bypassing limits by hitting different servers.

```text
User → Server 1 → counter = 1  ✅
User → Server 2 → counter = 1  ✅  (should be 2!)
User → Server 3 → counter = 1  ✅  (should be 3!)
```

--------------------------------

### POST /api/v1/keys — Register API Key

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Registers a new API key with a specified rate limit policy. Supports 'sliding_window' and 'token_bucket' algorithms.

```APIDOC
## POST /api/v1/keys

### Description
Registers a new API key with a rate limit policy. Choose between `sliding_window` (recommended for precise enforcement) or `token_bucket` (for bursty traffic patterns).

### Method
POST

### Endpoint
/api/v1/keys

### Parameters
#### Request Body
- **algorithm** (string) - Required - The rate limiting algorithm to use. Options: `sliding_window`, `token_bucket`.
- **limit** (integer) - Required - The maximum number of requests allowed within the `windowSeconds`.
- **windowSeconds** (integer) - Required - The duration of the rate limiting window in seconds.

### Request Example
```json
{
  "algorithm": "sliding_window",
  "limit": 100,
  "windowSeconds": 60
}
```

### Response
#### Success Response (201 Created)
- **apiKey** (string) - The newly registered API key.
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "apiKey": "abc123-def456-ghi789",
  "message": "API key registered successfully"
}
```
```

--------------------------------

### POST /api/v1/keys - Register API Key

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

Registers a new API key with a specified rate limiting policy.

```APIDOC
## POST /api/v1/keys

### Description
Registers a new API key with a specified rate limiting policy.

### Method
POST

### Endpoint
/api/v1/keys

### Request Body
- **algorithm** (string) - Required - The rate limiting algorithm to use (e.g., "sliding_window").
- **limit** (integer) - Required - The maximum number of requests allowed.
- **windowSeconds** (integer) - Required - The time window in seconds for the limit.

### Request Example
```json
{
  "algorithm": "sliding_window",
  "limit": 100,
  "windowSeconds": 60
}
```
```

--------------------------------

### TypeScript SDK - RateLimiter Class

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Initialization of the RateLimiter class from the TypeScript SDK, which handles communication with the rate limiter service and includes features like circuit breaker and local caching.

```APIDOC
## TypeScript SDK - RateLimiter Class

### Description
The main SDK class that handles communication with the rate limiter service. Includes built-in circuit breaker, local caching, and configurable fail-open behavior.

### Initialization
```typescript
import { RateLimiter } from '@rajvardhan6403/rate-limiter-sdk';

// Full configuration with all options
const limiter = new RateLimiter({
  serviceUrl: 'https://distributed-rate-limiter-production-82bf.up.railway.app',
  apiKey: 'your-api-key',
  failOpen: true,           // Allow requests if service is down (default: true)
  timeoutMs: 3000,          // HTTP timeout in milliseconds (default: 3000)
  localCacheTtlMs: 1000,    // Cache deny decisions for 1 second (default: 1000)
});

// Minimal configuration
const limiterMinimal = new RateLimiter({
  serviceUrl: 'http://localhost',
  apiKey: 'your-api-key',
});
```

### Options
- **serviceUrl** (string) - Required - The base URL of the distributed rate limiter service.
- **apiKey** (string) - Required - The API key to use for authentication.
- **failOpen** (boolean) - Optional - If true, requests are allowed if the service is down. Defaults to true.
- **timeoutMs** (number) - Optional - The HTTP request timeout in milliseconds. Defaults to 3000.
- **localCacheTtlMs** (number) - Optional - The time-to-live for local cache of deny decisions in milliseconds. Defaults to 1000.
```

--------------------------------

### Check Rate Limit for a User

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Checks if a request is allowed based on the rate limit policy associated with the provided API key and client identifier. Returns status, remaining requests, and reset time.

```bash
curl -X POST https://distributed-rate-limiter-production-82bf.up.railway.app/api/v1/check \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your-api-key",
    "identifier": "user-123",
    "cost": 1
  }'
```

--------------------------------

### Check Rate Limit with limiter.check()

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Use limiter.check() to programmatically determine if a request should be allowed based on rate limits. It returns a promise with decision and metadata. You can specify a custom cost to consume multiple tokens.

```typescript
import {
  RateLimiter
} from '@rajvardhan6403/rate-limiter-sdk';

const limiter = new RateLimiter({
  serviceUrl: 'https://distributed-rate-limiter-production-82bf.up.railway.app',
  apiKey: 'your-api-key',
});

// Basic check using IP address as identifier
async function handleRequest(req: Request) {
  const result = await limiter.check({
    identifier: req.ip,
  });

  if (!result.allowed) {
    return new Response(JSON.stringify({
      error: 'Rate limit exceeded',
      retryAfter: result.retryAfterSeconds,
    }), {
      status: 429,
      headers: {
        'Retry-After': String(result.retryAfterSeconds),
        'X-RateLimit-Remaining': String(result.remaining),
      },
    });
  }

  // Process the allowed request
  return new Response('Success');
}

// Check with custom cost (for expensive operations)
const expensiveResult = await limiter.check({
  identifier: 'user-123',
  cost: 5,  // Consumes 5 tokens instead of 1
});

// Result object structure:
// {
//   allowed: boolean,        // true if request is allowed
//   remaining: number,       // requests remaining in window
//   limit: number,           // total limit configured
//   windowSeconds: number,   // window size in seconds
//   resetAtEpochMs: number,  // when window resets (epoch ms)
//   retryAfterSeconds: number // seconds to wait if denied (0 if allowed)
// }
```

--------------------------------

### Integrate Rate Limiter as Express Middleware

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

Integrate the RateLimiter as Express middleware by using the .middleware() method. This applies rate limiting to all defined routes.

```typescript
import express from 'express';
import { RateLimiter } from '@rajvardhan6403/rate-limiter-sdk';

const app = express();
const limiter = new RateLimiter({
  serviceUrl: 'https://distributed-rate-limiter-production-82bf.up.railway.app',
  apiKey: 'your-api-key',
});

app.use(limiter.middleware());  // all routes are now rate limited
```

--------------------------------

### Rate Limit Check Response (Allowed)

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

JSON response when a request is allowed. Includes allowed status, remaining requests, reset time, and policy details.

```json
{
  "allowed": true,
  "remaining": 4,
  "resetAtEpochMs": 1234567890000,
  "retryAfterSeconds": 0,
  "limit": 5,
  "windowSeconds": 30
}
```

--------------------------------

### Perform Basic Rate Limit Check

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/sdk/README.md

Perform a rate limit check for a specific identifier, optionally specifying the cost. Logs the result, including remaining requests and retry information.

```typescript
const result = await limiter.check({
  identifier: 'user-123',  // identifies who is making the request
  cost: 1                   // how many tokens to consume (default: 1)
});

console.log(result.allowed);          // true or false
console.log(result.remaining);        // how many requests left
console.log(result.retryAfterSeconds) // seconds to wait if denied
```

--------------------------------

### Check Rate Limit with Custom Cost

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Performs a rate limit check where the cost of the request is explicitly defined, allowing for variable consumption of rate limit tokens. This is useful for requests that consume more resources.

```bash
curl -X POST https://distributed-rate-limiter-production-82bf.up.railway.app/api/v1/check \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your-api-key",
    "identifier": "user-123",
    "cost": 5
  }'
```

--------------------------------

### Monitoring with Grafana

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

Overview of the metrics available in the Grafana dashboard for monitoring the rate limiter service.

```APIDOC
## Monitoring

The Grafana dashboard at `http://localhost:3000` provides insights into the rate limiter's performance. Key metrics include:

- **HTTP Requests per Second**: Traffic volume across all service instances.
- **Average Response Time**: Latency of API endpoints in milliseconds.
- **JVM Heap Memory**: Memory usage per service instance in megabytes.
- **Live JVM Threads**: Number of active threads per service instance.
```

--------------------------------

### Check Rate Limit via Direct HTTP API (Python)

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

Make a POST request to the /api/v1/check endpoint using Python's requests library to check rate limits. Handles JSON payload and response parsing.

```python
import requests

response = requests.post(
    'https://distributed-rate-limiter-production-82bf.up.railway.app/api/v1/check',
    json={'apiKey': 'your-api-key', 'identifier': 'user-123', 'cost': 1}
)
data = response.json()
if not data['allowed']:
    print(f"Rate limited. Retry after {data['retryAfterSeconds']} seconds")
```

--------------------------------

### Flask Middleware for Rate Limiting

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Integrates rate limiting into Flask routes using a decorator. Ensures requests from the same IP address are within defined limits.

```python
from flask import Flask, request, jsonify
from functools import wraps

app = Flask(__name__)

def rate_limit(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        result = limiter.check(identifier=request.remote_addr)
        if not result['allowed']:
            return jsonify({
                'error': 'Rate limit exceeded',
                'retryAfter': result['retryAfterSeconds']
            }), 429
        return f(*args, **kwargs)
    return decorated

@app.route('/api/data')
@rate_limit
def get_data():
    return jsonify({'data': 'success'})
```

--------------------------------

### Sliding Window Rate Limiter Lua Script

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

An atomic Lua script for Redis that implements the sliding window rate limiting algorithm. It removes expired entries, checks the current count, and adds a new request if the limit is not exceeded.

```lua
redis.call('ZREMRANGEBYSCORE', key, 0, now - windowMs)
local count = redis.call('ZCARD', key)
if count < limit then
    redis.call('ZADD', key, now, requestId)
    return {1, limit - count - 1}
end
return {0, 0}
```

--------------------------------

### limiter.middleware() - Express

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Factory function that returns Express middleware for automatic rate limiting on all routes.

```APIDOC
## Use Express Middleware

### Description
Applies rate limiting automatically to Express routes using middleware.

### Method
USE (Express middleware)

### Endpoint
Applies to routes specified during middleware setup.

### Parameters
#### Middleware Options (Optional Function Argument)
- **identifier** (function) - Optional - A function that takes the Express request object and returns a unique identifier string. Defaults to using `req.ip`.
- **cost** (number) - Optional - The cost of each request in tokens. Defaults to 1.

### Request Example (Applying to all routes)
```typescript
import express from 'express';
import { RateLimiter } from '@rajvardhan6403/rate-limiter-sdk';

const app = express();
const limiter = new RateLimiter({ serviceUrl: '...', apiKey: '...' });

app.use(limiter.middleware());
```

### Request Example (Applying to specific routes with custom identifier)
```typescript
app.use('/api', limiter.middleware((req) => req.headers['x-user-id'] as string || req.ip));
```

### Response Headers (Set by Middleware)
- **X-RateLimit-Limit** (number) - Total requests allowed in the window.
- **X-RateLimit-Remaining** (number) - Requests remaining in the current window.
- **X-RateLimit-Reset** (number) - The timestamp (epoch ms) when the window resets.
- **Retry-After** (number) - Seconds to wait before retrying (only on 429 responses).
```

--------------------------------

### Delete API Key

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Deletes an existing API key and all its associated rate limiting data from the system. This action is irreversible.

```bash
curl -X DELETE https://distributed-rate-limiter-production-82bf.up.railway.app/api/v1/keys/your-api-key
```

--------------------------------

### limiter.check() - Node.js

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Checks whether a request should be allowed. Returns a promise with the rate limit decision and metadata.

```APIDOC
## POST /api/v1/check

### Description
Checks whether a request should be allowed. Returns a promise with the rate limit decision and metadata.

### Method
POST

### Endpoint
/api/v1/check

### Parameters
#### Request Body
- **apiKey** (string) - Required - Your API key for authentication.
- **identifier** (string) - Required - A unique identifier for the entity being rate limited (e.g., IP address, user ID).
- **cost** (number) - Optional - The cost of the request in tokens. Defaults to 1.

### Request Example
```json
{
  "apiKey": "your-api-key",
  "identifier": "user-ip-address",
  "cost": 1
}
```

### Response
#### Success Response (200)
- **allowed** (boolean) - Indicates if the request is allowed.
- **remaining** (number) - The number of requests remaining in the current window.
- **limit** (number) - The total limit configured for the window.
- **windowSeconds** (number) - The duration of the rate limiting window in seconds.
- **resetAtEpochMs** (number) - The timestamp (in epoch milliseconds) when the rate limiting window resets.
- **retryAfterSeconds** (number) - The number of seconds to wait before retrying if the request is denied. 0 if allowed.

#### Response Example
```json
{
  "allowed": true,
  "remaining": 9,
  "limit": 10,
  "windowSeconds": 60,
  "resetAtEpochMs": 1678886400000,
  "retryAfterSeconds": 0
}
```
```

--------------------------------

### Apply Express Middleware with limiter.middleware()

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

Use limiter.middleware() to automatically apply rate limiting to all Express routes. It uses the IP address as the default identifier but can be configured to extract custom identifiers from requests.

```typescript
import express from 'express';
import { RateLimiter } from '@rajvardhan6403/rate-limiter-sdk';

const app = express();

const limiter = new RateLimiter({
  serviceUrl: 'https://distributed-rate-limiter-production-82bf.up.railway.app',
  apiKey: 'your-api-key',
  failOpen: true,
});

// Apply to all routes — uses IP address as default identifier
app.use(limiter.middleware());

// Apply to specific routes with custom identifier extraction
app.use('/api', limiter.middleware((req) => {
  // Use user ID from auth header, fall back to IP
  return req.headers['x-user-id'] as string || req.ip;
}));

// Protected routes
app.get('/api/data', (req, res) => {
  res.json({ message: 'This endpoint is rate limited' });
});

app.get('/api/expensive', (req, res) => {
  res.json({ data: 'expensive computation result' });
});

// The middleware automatically sets these response headers:
// - X-RateLimit-Limit: total requests allowed
// - X-RateLimit-Remaining: requests remaining in window
// - X-RateLimit-Reset: when the window resets (epoch ms)
// - Retry-After: seconds to wait (only on 429 responses)

app.listen(3000, () => {
  console.log('Server running with distributed rate limiting');
});
```

--------------------------------

### Rate Limit Check Response (Rate Limited)

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

JSON response when a request is rate limited (HTTP 429). Indicates that the request is not allowed and provides the time until the next retry.

```json
{ "allowed": false, "remaining": 0, "retryAfterSeconds": 30 }
```

--------------------------------

### Register API Key Policy

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

JSON payload for registering a new API key with a specific rate limiting policy. Specifies the algorithm, limit, and window duration.

```json
{ "algorithm": "sliding_window", "limit": 100, "windowSeconds": 60 }
```

--------------------------------

### POST /api/v1/check - Check Rate Limit

Source: https://github.com/raj-deshmukh6403/distributed-rate-limiter/blob/main/README.md

Checks if a request is allowed based on the rate limiting policy.

```APIDOC
## POST /api/v1/check

### Description
Checks if a request is allowed based on the rate limiting policy associated with the provided API key.

### Method
POST

### Endpoint
/api/v1/check

### Parameters
#### Request Body
- **apiKey** (string) - Required - The API key for authentication.
- **identifier** (string) - Required - A unique identifier for the entity being rate limited (e.g., user ID, IP address).
- **cost** (integer) - Optional - The cost of the request, defaults to 1.

### Request Example
```json
{
  "apiKey": "abc123",
  "identifier": "user-456",
  "cost": 1
}
```

### Response
#### Success Response (200)
- **allowed** (boolean) - True if the request is allowed, false otherwise.
- **remaining** (integer) - The number of requests remaining in the current window.
- **resetAtEpochMs** (integer) - The epoch timestamp in milliseconds when the rate limit resets.
- **retryAfterSeconds** (integer) - The number of seconds to wait before retrying if the request is rate limited.
- **limit** (integer) - The total limit for the current window.
- **windowSeconds** (integer) - The duration of the rate limiting window in seconds.

#### Response Example (Allowed)
```json
{
  "allowed": true,
  "remaining": 4,
  "resetAtEpochMs": 1234567890000,
  "retryAfterSeconds": 0,
  "limit": 5,
  "windowSeconds": 30
}
```

#### Response Example (Rate Limited - 429)
```json
{
  "allowed": false,
  "remaining": 0,
  "retryAfterSeconds": 30
}
```
```

--------------------------------

### POST /api/v1/check — Check Rate Limit

Source: https://context7.com/raj-deshmukh6403/distributed-rate-limiter/llms.txt

The core endpoint to check if a request should be allowed based on the API key and identifier. Returns 200 if allowed, 429 if rate limited.

```APIDOC
## POST /api/v1/check

### Description
Core endpoint to check if a request should be allowed. Returns 200 if allowed, 429 if rate limited. The `identifier` field uniquely identifies the client (IP address, user ID, API key, etc.).

### Method
POST

### Endpoint
/api/v1/check

### Parameters
#### Request Body
- **apiKey** (string) - Required - The API key associated with the rate limit policy.
- **identifier** (string) - Required - A unique identifier for the client making the request.
- **cost** (integer) - Optional - The cost of the request, defaults to 1. Used to consume multiple tokens for a single request.

### Request Example
```json
{
  "apiKey": "your-api-key",
  "identifier": "user-123",
  "cost": 1
}
```

### Response
#### Success Response (200 OK)
- **allowed** (boolean) - True if the request is allowed, false otherwise.
- **remaining** (integer) - The number of requests remaining in the current window.
- **resetAtEpochMs** (integer) - The timestamp in milliseconds when the rate limit window resets.
- **retryAfterSeconds** (integer) - The number of seconds to wait before retrying the request (if rate limited).
- **limit** (integer) - The total limit for the current window.
- **windowSeconds** (integer) - The duration of the rate limiting window in seconds.

#### Response Example (Allowed)
```json
{
  "allowed": true,
  "remaining": 99,
  "resetAtEpochMs": 1734567890000,
  "retryAfterSeconds": 0,
  "limit": 100,
  "windowSeconds": 60
}
```

#### Error Response (429 Too Many Requests)
- **allowed** (boolean) - False.
- **remaining** (integer) - 0.
- **resetAtEpochMs** (integer) - The timestamp in milliseconds when the rate limit window resets.
- **retryAfterSeconds** (integer) - The number of seconds to wait before retrying.
- **limit** (integer) - The total limit for the current window.
- **windowSeconds** (integer) - The duration of the rate limiting window in seconds.

#### Response Example (Rate Limited)
```json
{
  "allowed": false,
  "remaining": 0,
  "resetAtEpochMs": 1734567890000,
  "retryAfterSeconds": 45,
  "limit": 100,
  "windowSeconds": 60
}
```
```