PM2 Token Bucket

Token bucket server for API throttling shared between instances using PM2 clusters.

Why?

When running a Node.js application in PM2 cluster mode, each instance operates independently.
If your app calls a rate-limited external API, every instance competes for the same quota — easily exceeding limits.

PM2 Token Bucket solves this by running a dedicated token server as a separate PM2 process.
All cluster instances request tokens from this central server via PM2's built-in IPC bus, ensuring a single, shared rate limit across your entire cluster.

┌──────────────────────────────────────────┐
│              PM2 Ecosystem               │
│                                          │
│   ┌──────────────────────────────────┐   │
│   │    TokenManager (server.js app)  │   │
│   │    Manages the shared bucket     │   │
│   └──────────────────────────────────┘   │
│              ▲                           │
│              │                           │
│              │ PM2 IPC Bus               │
│              │                           │
│     ┌────────┼────────┐                  │
│     ▼        ▼        ▼                  │
│  ┌──────┐ ┌──────┐ ┌──────┐              │
│  │ App  │ │ App  │ │ App  │              │
│  │ #0   │ │ #1   │ │ #2   │  (cluster)   │
│  └──────┘ └──────┘ └──────┘              │
└──────────────────────────────────────────┘

Installation

npm install pm2-token-bucket

Peer dependency: pm2 >= 6.0.0

Quick Start

You can see an example in the example directory of this repo, but here’s a quick overview of how to set it up:

1. Create the Token Server

Create a dedicated PM2 process that manages the shared token bucket.

// server.js
const { TokenManager } = require('pm2-token-bucket');

const tokenManager = new TokenManager({
    capacity: 10,          // Max tokens in the bucket
    refillRate: 1,         // Tokens added per refill
    refillInterval: 3000   // Refill every 3 seconds
});

tokenManager.start((err) => {
    if (err) {
        console.error("Failed to start TokenManager:", err);
    }
});

2. Consume Tokens in Your App

In your cluster application instances, use TokenClient to request tokens before making API calls.

// app.js
const express = require('express');
const { TokenClient } = require('pm2-token-bucket');

const app = express();
const tokenClient = new TokenClient();

app.use(async (req, res, next) => {
    try {
        if (await tokenClient.consume(1)) {
            next(); // Token granted — proceed
        } else {
            res.status(429).send('Too many requests');
        }
    } catch (err) {
        next(); // Fallback: allow on error
    }
});

app.get('/', (req, res) => {
    res.sendStatus(200);
});

app.listen(process.env.PORT || 3000);

3. Configure PM2 Ecosystem

Launch you app X times in cluster mode, and add 1 token server as a separate process.

// ecosystem.config.js
module.exports = {
    apps: [{
        name: "tokenServer",
        script: "./server.js"
    }, {
        name: "clientApp",
        script: "./app.js",
        instances: 3,
        exec_mode: "cluster"
    }]
};

4. Start Everything

pm2 start ecosystem.config.js

API Reference

TokenManager

The server-side class that manages the token bucket.
Run this in a separate, single PM2 process.

new TokenManager(options?)

| Option | Type | Default | Description | | ---------------- | -------- | ------- | ---------------------------------------- | | capacity | number | 100 | Maximum number of tokens in the bucket | | refillRate | number | 10 | Number of tokens added per refill cycle | | refillInterval | number | 1000 | Milliseconds between each refill cycle |

tokenManager.start(errCallback?)

Connects to the PM2 bus and starts listening for token requests from cluster instances.

• errCallback (optional) — Called with an Error if the PM2 bus connection fails.

tokenManager.getStatus()

Returns the current state of the bucket:

{
    tokens: 8,           // Current available tokens
    capacity: 10,        // Maximum capacity
    refillRate: 1,       // Tokens per refill
    refillInterval: 3000 // Refill interval in ms
}

TokenClient

The client-side class used within your cluster instances to request tokens.

new TokenClient()

Creates a new client and starts listening for responses from the TokenManager.

tokenClient.consume(amount?)

Requests tokens from the TokenManager.

| Parameter | Type | Default | Description | | --------- | -------- | ------- | ------------------------------- | | amount | number | 1 | Number of tokens to consume |

Returns: Promise<boolean>

• true — tokens were granted
• false — not enough tokens available (rate limited)
• true (on timeout) — if the TokenManager doesn't respond within 500ms, the request is allowed as a safety fallback

Note: If the process is not running under PM2 (i.e. process.send is unavailable), consume() always resolves to true, making it safe to use in development without PM2.

How It Works

1. The TokenManager runs as a standalone PM2 process and holds a token bucket that refills at a configurable rate.
2. Each TokenClient instance (in your clustered app) sends a token request over PM2's IPC bus.
3. The TokenManager checks the bucket, deducts tokens if available, and sends back an allowed / denied response.
4. The TokenClient resolves its consume() promise accordingly.

All communication happens through PM2's built-in inter-process messaging — no external dependencies like Redis or HTTP servers required.

Running the Example

# Clone the repo and install dependencies
npm install

# Build the TypeScript source
npm run build

# Start the example with PM2 and run a load test
cd example
pm2 start ecosystem.config.js
npx loadtest -n 30 -c 10 http://localhost:3000/

License

This project is licensed under CC BY-NC-SA.