@operationcaribbeansummer/wikiagora-limiter

v4.0.0

Published

a month ago

🚦⛔-(mlk)[]{} Rate limiting middleware for WikiAgora API protection - prevents abuse and manages traffic by user role, IP address, HTTP method, and endpoint

Downloads

0High
0Medium
0Low

javiramoslab

OperationCaribbeanSummer WikiAgora 44 mlk mlk44

WikiAgora-limiter

📝 Description

Short description: Rate limiting middleware for WikiAgora API protection - prevents abuse and manages traffic by user role, IP address, HTTP method, and endpoint

Keywords: node, npm-package, utility, OperationCaribbeanSummer, WikiAgora, 44, mlk, mlk44.

✨ Features

Core Functionalities

✅ Dynamic Role-Based Rate Limiting - Automatically adjusts limits based on user roles (admin, user, bot, guest)
✅ HTTP Method-Aware Limiting - Configurable multipliers for different HTTP methods (GET, POST, PATCH, PUT, DELETE)
✅ Intelligent User Tracking - Authenticated users tracked by user ID, unauthenticated users tracked by IP address
✅ Flexible Configuration Modes - Choose between fixed numeric limits or dynamic calculation (role × method multipliers)
✅ Standard Headers Support - Supports draft-6, draft-7, and draft-8 rate limit headers for client-side awareness
✅ Request Method Skipping - Bypass rate limiting for specific HTTP methods (default: HEAD, OPTIONS)
✅ IPv6 Subnet Grouping - Configurable IPv6 subnet size (48-64) for aggressive or relaxed IP grouping
✅ Custom Error Responses - Customize status code and message when rate limit is exceeded
✅ Express Middleware Integration - Seamless integration with Express.js applications
✅ Zero Runtime Dependencies - Only requires express-rate-limit as a bundled dependency

Advanced Capabilities

✅ Asynchronous Limit Calculation - Dynamic limit calculation using async functions for complex scenarios
✅ Per-Request Context Awareness - Access to request object (req.user, req.method, req.ip) for intelligent decisions
✅ Configurable Time Windows - Customizable time window duration (default: 15 minutes / 900000ms)
✅ Legacy Header Control - Enable/disable legacy X-RateLimit-* headers independently
✅ Role Detection - Automatic detection from req.user.role with fallback to guest mode
✅ Method-Specific Limits - Granular control over read (GET), write (POST/PATCH/PUT), and destructive (DELETE) operations

Use Cases

🛡️ API Abuse Prevention - Protect your API from excessive requests and potential DDoS attacks
👥 Tiered Access Control - Provide different rate limits for free users, premium users, admins, and bots
📊 Traffic Management - Balance load across different endpoints based on their resource intensity
🔒 Security Enhancement - Add an additional layer of security by limiting request frequency
💰 Resource Optimization - Prevent server overload and optimize resource allocation

More ideas and feature requests are welcome – open an issue

📦 Tech stack

Runtime: Node.js (>=20)
Language: JavaScript (CommonJS)
Framework: Express.js (^4.21.0)
Package manager: npm / pnpm
Rate Limiting: express-rate-limit (^8.5.2)
Testing: Vitest (^4.1.6), Supertest (^7.1.4)
Linting / formatting: StandardJS (^17.1.2)
CI/CD: GitHub Actions
Database: MongoDB (via Mongoose ^8.19.0, peer dependency)
Configuration: dotenv (^17.2.3, peer dependency)

For a detailed list of dependencies, see package.json.

🚀 Quick Start

Prerequisites

Node.js >=20
npm >=10 or pnpm >=7

Installation

npm install @operationcaribbeansummer/wikiagora-limiter

Basic Usage

// CommonJS
const { limiter44 } = require("@operationcaribbeansummer/wikiagora-limiter");

// ES Modules (if supported)
// import { limiter44 } from "@operationcaribbeansummer/wikiagora-limiter";

// globally
app.use(limiter44);

Example 1: Fixed Rate Limit

const express = require('express');
const { limiter44 } = require('@operationcaribbeansummer/wikiagora-limiter');

const app = express();

// Apply rate limiter with fixed limit
const limiter = limiter44({
  windowMs: 60000,  // 1 minute
  limit: 50         // 50 requests per window
});

app.use('/api', limiter);

app.listen(4444, () => {
  console.log('Server running on port 4444');
});

Example 2: Dynamic Role-Based and Method-Based Limiting

const express = require('express');
const { limiter44 } = require('@operationcaribbeansummer/wikiagora-limiter');

const app = express();

// Apply dynamic rate limiter
const limiter = limiter44({
  windowMs: 900000,  // 15 minutes
  limit: {
    userRoleDefault: 1,   // Guest multiplier
    userRoleAdmin: 5,     // Admin multiplier
    userRoleBot: 3,       // Bot multiplier
    userRoleUser: 2,      // Regular user multiplier
    httpMethodGet: 444,   // GET multiplier
    httpMethodPost: 44,   // POST multiplier
    httpMethodPatch: 30,  // PATCH multiplier
    httpMethodPut: 20,    // PUT multiplier
    httpMethodDelete: 4   // DELETE multiplier
  },
  skipMethods: ['HEAD', 'OPTIONS'],  // Skip these methods
  standardHeaders: true,              // Enable standard headers
  legacyHeaders: false                // Disable legacy headers
});

app.use('/api', limiter);

app.listen(4444, () => {
  console.log('Server running on port 4444');
});

Example 3: Custom Error Message

const limiter = limiter44({
  windowMs: 60000,
  limit: 100,
  message: { 
    status: 429, 
    message: "Rate limit exceeded. Please slow down." 
  }
});

app.use('/api', limiter);

⚙️ Configuration

The limiter44 function accepts a configuration object with the following options:

Configuration Options

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | windowMs | number | 900000 (15 min) | Time window in milliseconds | | limit | number\|object | - | Rate limit: fixed number or dynamic config object | | standardHeaders | boolean\|string | true | Enable standard headers (true, 'draft-6', 'draft-7', 'draft-8') | | legacyHeaders | boolean | false | Enable/disable legacy X-RateLimit-* headers | | ipv6Subnet | number | 56 | IPv6 subnet size (48-64, lower = more aggressive grouping) | | message | object\|string | - | Custom response when rate limit exceeded | | skipMethods | string[] | ['HEAD', 'OPTIONS'] | HTTP methods to skip rate limiting |

Dynamic Limit Configuration

When limit is an object, it supports these properties:

User Role Multipliers:

userRoleDefault - Base multiplier for guest/unauthenticated users (default: 1)
userRoleAdmin - Base multiplier for admin users (default: 5)
userRoleBot - Base multiplier for bot users (default: 3)
userRoleUser - Base multiplier for regular authenticated users (default: 2)

HTTP Method Multipliers:

httpMethodGet - Multiplier for GET requests (default: 444)
httpMethodPost - Multiplier for POST requests (default: 44)
httpMethodPatch - Multiplier for PATCH requests (default: 30)
httpMethodPut - Multiplier for PUT requests (default: 20)
httpMethodDelete - Multiplier for DELETE requests (default: 4)
httpMethodDefault - Multiplier for unspecified methods (default: 4)

For advanced configuration, see docs/configuration.md.

📚 Documentation

Build docs locally

npm run docs

🧪 Testing

Run the test suite:

npm test

Run coverage:

npm run coverage

We use Vitest and aim for >90% coverage.

🤝 Contributing

We welcome contributions! Please read our Contributing Guidelines and Code of Conduct.

How to contribute

Fork the repo
Create a feature branch (git checkout -b feat/amazing-feature)
Commit changes using Conventional Commits
Push to the branch
Open a Pull Request

Commit conventions

We follow Conventional Commits:

feat: new feature
fix: bug fix
docs: documentation
test: adding tests
chore: maintenance
breaking: breaking change

Branching strategy

We use GitHub Flow:

main – production-ready code
feat/* – feature branches
fix/* – bug fixes
docs/* – documentation updates

🛣️ Roadmap

See the open issues and milestones for planned features and bugfixes.

💬 Support

🙏 Credits

Author: Javier Ramos @JaviRamosLab

Contributors: see CONTRIBUTORS.md

👩‍⚖️License

Code released under MIT License / content under CC-BY-SA

Copyleft (ɔ) 2026+, OperationCaribbeanSummer contributors https://github.com/orgs/OperationCaribbeanSummer/people

Copyleft (ɔ) 2023-2026, Javier Ramos Nistal https://github.com/JaviRamosLab